% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_eolid.R
\name{get_eolid}
\alias{get_eolid}
\alias{as.eolid}
\alias{as.eolid.eolid}
\alias{as.eolid.character}
\alias{as.eolid.list}
\alias{as.eolid.numeric}
\alias{as.eolid.data.frame}
\alias{as.data.frame.eolid}
\alias{get_eolid_}
\title{Get the EOL ID from Encyclopedia of Life from taxonomic names.}
\usage{
get_eolid(
  sciname,
  ask = TRUE,
  messages = TRUE,
  rows = NA,
  rank = NULL,
  data_source = NULL,
  ...
)

as.eolid(x, check = TRUE)

\method{as.eolid}{eolid}(x, check = TRUE)

\method{as.eolid}{character}(x, check = TRUE)

\method{as.eolid}{list}(x, check = TRUE)

\method{as.eolid}{numeric}(x, check = TRUE)

\method{as.eolid}{data.frame}(x, check = TRUE)

\method{as.data.frame}{eolid}(x, ...)

get_eolid_(sciname, messages = TRUE, rows = NA, ...)
}
\arguments{
\item{sciname}{character; one or more scientific or common names. Or,
a \code{taxon_state} object (see \link{taxon-state})}

\item{ask}{logical; should get_eolid be run in interactive mode?
If TRUE and more than one ID is found for the species, the user is asked for
input. If FALSE NA is returned for multiple matches.}

\item{messages}{logical; If \code{TRUE} the actual taxon queried is printed
on the console.}

\item{rows}{numeric; Any number from 1 to infinity. If the default NA, all
rows are considered. Note that this function still only gives back a eolid
class object with one to many identifiers. See
\code{\link[=get_eolid_]{get_eolid_()}} to get back all, or a subset, of the raw
data that you are presented during the ask process.}

\item{rank}{(character) A taxonomic rank name. See \code{\link[=rank_ref]{rank_ref()}}
for possible options. Though note that some data sources use atypical ranks,
so inspect the data itself for options. Optional. See \code{Filtering} below.}

\item{data_source}{(character) A data source inside of EOL. These are
longish names like e.g., "Barcode of Life Data Systems" or
"USDA PLANTS images". Optional. See \code{Filtering} below.}

\item{...}{Further args passed on to \code{\link[=eol_search]{eol_search()}}}

\item{x}{Input to \code{\link[=as.eolid]{as.eolid()}}}

\item{check}{logical; Check if ID matches any existing on the DB, only
used in \code{\link[=as.eolid]{as.eolid()}}}
}
\value{
A vector of taxonomic identifiers as an S3 class.
If a taxon is not found an \code{NA} is given. If more than one identifier
is found the function asks for user input if \code{ask = TRUE}, otherwise
returns \code{NA}. If \code{ask=FALSE} and \code{rows} does not equal
\code{NA}, then a data.frame is given back, but not of the uid class, which
you can't pass on to other functions as you normally can.

See \code{\link{get_id_details}} for further details including
attributes and exceptions
}
\description{
Note that EOL doesn't expose an API endpoint for directly querying for EOL
taxon ID's, so we first use the function \code{\link[=eol_search]{eol_search()}}
to find pages that deal with the species of interest, then use
\code{\link[=eol_pages]{eol_pages()}} to find the actual taxon IDs.
}
\details{
EOL is a bit odd in that they have page IDs for each taxon, but
then within that, they have taxon ids for various taxa within that page
(e.g., GBIF and NCBI each have a taxon they refer to within the
page [i.e., taxon]). And we need the taxon ids from a particular data
provider (e.g, NCBI) to do other things, like get a higher classification
tree. However, humans want the page id, not the taxon id. So, the
id returned from this function is the taxon id, not the page id. You can
get the page id for a taxon by using \code{\link[=eol_search]{eol_search()}} and
`\code{\link[=eol_pages]{eol_pages()}}, and the URI returned in the attributes for a
taxon will lead you to the taxon page, and the ID in the URL is the
page id.
}
\section{Filtering}{

The parameters \code{rank} and \code{data_source} are not used in the
search to the data provider, but are used in filtering the data down to a
subset that is closer to the target you want.  For all these parameters,
you can use regex strings since we use \code{\link[=grep]{grep()}} internally to
match. Filtering narrows down to the set that matches your query, and
removes the rest.
}

\examples{
\dontrun{
get_eolid(sciname='Pinus contorta')
get_eolid(sciname='Puma concolor')

get_eolid(c("Puma concolor", "Pinus contorta"))

# specify rows to limit choices available
get_eolid('Poa annua')
get_eolid('Poa annua', rows=1)
get_eolid('Poa annua', rows=2)
get_eolid('Poa annua', rows=1:2)

# When not found
get_eolid(sciname="uaudnadndj")
get_eolid(c("Chironomus riparius", "uaudnadndj"))

# filter results to a rank or data source, or both
get_eolid("Satyrium")
get_eolid("Satyrium", rank = "genus")
get_eolid("Satyrium", data_source = "INAT")
get_eolid("Satyrium", rank = "genus",
  data_source = "North Pacific Species List")

# Convert a eolid without class information to a eolid class
# already a eolid, returns the same
as.eolid(get_eolid("Chironomus riparius"))
# same
as.eolid(get_eolid(c("Chironomus riparius","Pinus contorta")))
# numeric
as.eolid(10247706)
# numeric vector, length > 1
as.eolid(c(6985636,12188704,10247706))
# character
as.eolid("6985636")
# character vector, length > 1
as.eolid(c("6985636","12188704","10247706"))
# list, either numeric or character
as.eolid(list("6985636","12188704","10247706"))
## dont check, much faster
as.eolid("6985636", check=FALSE)
as.eolid(6985636, check=FALSE)
as.eolid(c("6985636","12188704","10247706"), check=FALSE)
as.eolid(list("6985636","12188704","10247706"), check=FALSE)

(out <- as.eolid(c(6985636,12188704,10247706)))
data.frame(out)
as.eolid( data.frame(out) )

# Get all data back
get_eolid_("Poa annua")
get_eolid_("Poa annua", rows=2)
get_eolid_("Poa annua", rows=1:2)
get_eolid_(c("asdfadfasd", "Pinus contorta"))
}
}
\seealso{
\code{\link[=classification]{classification()}}

Other taxonomic-ids: 
\code{\link{get_boldid}()},
\code{\link{get_gbifid}()},
\code{\link{get_ids}()},
\code{\link{get_iucn}()},
\code{\link{get_natservid}()},
\code{\link{get_nbnid}()},
\code{\link{get_pow}()},
\code{\link{get_tolid}()},
\code{\link{get_tpsid}()},
\code{\link{get_tsn}()},
\code{\link{get_uid}()},
\code{\link{get_wiki}()},
\code{\link{get_wormsid}()}
}
\author{
Scott Chamberlain, \email{myrmecocystus@gmail.com}
}
\concept{taxonomic-ids}
