% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/col_downstream.R
\name{col_downstream}
\alias{col_downstream}
\title{Use Catalogue of Life to get downstream taxa to a given taxonomic level}
\usage{
col_downstream(name = NULL, id = NULL, downto, format = NULL,
  start = NULL, checklist = NULL, messages = TRUE,
  intermediate = FALSE, extant_only = FALSE, ...)
}
\arguments{
\item{name}{The string to search for. Only exact matches found the name given
will be returned, unless one or wildcards are included in the search
string. An * (asterisk) character denotes a wildcard; a percent
character may also be used. The name must be at least 3 characters long,
not counting wildcard characters.}

\item{id}{The record ID of the specific record to return (only for scientific
names of species or infraspecific taxa)}

\item{downto}{The taxonomic level you want to go down to. See examples below.
The taxonomic level IS case sensitive, and you do have to spell it
correctly. See \code{data(rank_ref)} for spelling.}

\item{format}{The returned format (default = NULL). If NULL xml is used.
Currently only xml is supported.}

\item{start}{The first record to return (default = NULL). If NULL, the
results are returned from the first record (start=0). This is useful if
the total number of results is larger than the maximum number of results
returned by a single Web service query (currently the maximum number of
results returned by a single query is 500 for terse queries and 50 for
full queries).}

\item{checklist}{The year of the checklist to query, if you want a specific
year's checklist instead of the lastest as default (numeric).}

\item{messages}{Print or suppress messages.}

\item{intermediate}{(logical) If \code{TRUE}, return a list of length two
with target taxon rank names, with additional list of data.frame's of
intermediate taxonomic groups. Default: \code{FALSE}}

\item{extant_only}{(logical) keep extant taxa only? default: \code{FALSE}.
by default we give back all taxa. set to \code{TRUE} to get only
extant taxa}

\item{...}{Curl options passed on to \link[crul:verb-GET]{crul::verb-GET}}
}
\value{
A list of data.frame's, where each data.frame has columns:
\itemize{
\item childtaxa_id: (character) COL identifier
\item childtaxa_name: (character) taxonomic name
\item childtaxa_rank: (character) rank name
\item childtaxa_extinct: (logical) extinct or not
}
}
\description{
Use Catalogue of Life to get downstream taxa to a given taxonomic level
}
\details{
Provide only names instead of id's
}
\section{Rate limiting}{

COL introduced rate limiting recently (writing this on 2019-11-14),
but we've no information on what the rate limits are. If you do run into
this you'll see an error like "Error: Too Many Requests (HTTP 429)",
you'll need to time your requests to avoid the rate limiting, for
example, by putting \code{Sys.sleep()} in between simultaneous requests.
}

\examples{
\dontrun{
# Some basic examples
col_downstream(name="Apis", downto="species")
col_downstream(name="Bryophyta", downto="family")

# get classes down from the kingdom Animalia
col_downstream(name="Animalia", downto="class")
col_downstream(name="Animalia", downto="class", intermediate=TRUE)

# An example that takes a bit longer
col_downstream(name=c("Plantae", "Animalia"), downto="class")

# Using a checklist from a specific year
col_downstream(name="Bryophyta", downto="family", checklist=2009)

# By id
col_downstream(id='576d098d770a39d09e2bcfa1c0896b26', downto="species",
  checklist=2012)

# keep extant taxa only, prunes out extinct taxa
col_downstream(name = "Insecta", downto = "order")
col_downstream(name = "Insecta", downto = "order", extant_only = TRUE)
}
}
