Query the World Checklist of Vascular Plants search API for a taxon string.
search_wcvp(query, filters = NULL, cursor = "*", limit = 50, .wait = 0.1)The taxon string to search WCVP for. If using keywords, the query must be formatted as a list.
Filter to apply to search results. Multiple filters must be supplied as a character vector.
A cursor returned by a previous search. If used, the query and filter must be exactly the same.
An integer specifying the maximum number of results to return.
Time to wait before making a request, to help rate limiting.
Returns an object of class wcvp_search that is a simple
structure with slots for:
total: the total number of results held in WCVP for the query
cursor: a cursor to retrieve the next page of results from the API.
limit: the maximum number of results requested from the API.
results: the query results parsed into a list.
query: the query string submitted to the API.
filter: the filter strings submitted to the API.
response: the httr response object.
The World Checklist of Vascular Plants (WCVP) is a global consensus view of all known vascular plant species. It has been compiled by staff at RBG Kew in consultation with plant group experts.
The search API allows users to query the checklist for plant names. Currently, it does not support partial or fuzzy matching. In order to get a result, the user must supply a valid name string. For example, 'Myrcia' and 'Myrcia guianensis' will return results, but 'M' or 'Myr' will not.
There is some support for querying using keyword arguments. The API is
not currently documented, so only keywords that are definitely there have
been implemented. Use the get_keywords function to view a list of all implemented keywords.
The API will return taxonomic information (the family, authority, status, and rank)
of all names matching the query. These results can be limited, for example to accepted species,
using filters. Use the get_filters function to view a list of all implemented filters.
WCVP (2020). World Checklist of Vascular Plants, version 2.0. Facilitated by the Royal Botanic Gardens, Kew. Published on the Internet; http://wcvp.science.kew.org/
lookup_wcvp() to lookup information about a taxon name
using a valid IPNI ID.
download_wcvp() to download the entire WCVP.
Other WCVP functions:
download_wcvp(),
lookup_wcvp()
# search for all entries containing a genus name
search_wcvp("Myrcia")
#> <WCVP search: 'Myrcia' filters: 'none'>
#> total results: 1401
#> returned results: 50
#> total pages: 29
#> current page: 29
#> List of 1
#> $ :List of 9
#> ..$ id : chr "30001220-2"
#> ..$ fqId : chr "urn:lsid:ipni.org:names:30001220-2"
#> ..$ url : chr "/taxon/30001220-2"
#> ..$ display : chr "<b><i>Myrcia</i> D</i> C. <i>ex Guill.</b>"
#> ..$ accepted: logi TRUE
#> ..$ family : chr "Myrtaceae"
#> ..$ name : chr "Myrcia"
#> ..$ author : chr "DC. ex Guill."
#> ..$ rank : chr "Genus"
# search for all accepted species within a genus
search_wcvp("Myrcia", filters=c("species", "accepted"))
#> <WCVP search: 'Myrcia' filters: 'species, accepted'>
#> total results: 767
#> returned results: 50
#> total pages: 16
#> current page: 16
#> List of 1
#> $ :List of 9
#> ..$ id : chr "165525-2"
#> ..$ fqId : chr "urn:lsid:ipni.org:names:165525-2"
#> ..$ url : chr "/taxon/165525-2"
#> ..$ display : chr "<b><i>Myrcia abbotiana</i> (Urb.) Alain</b>"
#> ..$ accepted: logi TRUE
#> ..$ family : chr "Myrtaceae"
#> ..$ name : chr "Myrcia abbotiana"
#> ..$ author : chr "(Urb.) Alain"
#> ..$ rank : chr "Species"
# search for up to 10,000 species in a genus
search_wcvp("Poa", filters=c("species"), limit=10000)
#> <WCVP search: 'Poa' filters: 'species'>
#> total results: 1992
#> returned results: 1992
#> total pages: 1
#> current page: 1
#> List of 1
#> $ :List of 9
#> ..$ id : chr "416409-1"
#> ..$ fqId : chr "urn:lsid:ipni.org:names:416409-1"
#> ..$ url : chr "/taxon/416409-1"
#> ..$ display : chr "<b><i>Poa abbreviata</i> R.Br.</b>"
#> ..$ accepted: logi TRUE
#> ..$ family : chr "Poaceae"
#> ..$ name : chr "Poa abbreviata"
#> ..$ author : chr "R.Br."
#> ..$ rank : chr "Species"
# search for all names in a family
search_wcvp(list(family="Myrtaceae"))
#> <WCVP search: family='Myrtaceae' filters: 'none'>
#> total results: 17600
#> returned results: 50
#> total pages: 352
#> current page: 352
#> List of 1
#> $ :List of 10
#> ..$ id : chr "27387-1"
#> ..$ fqId : chr "urn:lsid:ipni.org:names:27387-1"
#> ..$ url : chr "/taxon/27387-1"
#> ..$ display : chr "<i>Abbevillea</i> O.Berg"
#> ..$ accepted : logi FALSE
#> ..$ synonymOf:List of 9
#> ..$ family : chr "Myrtaceae"
#> ..$ name : chr "Abbevillea"
#> ..$ author : chr "O.Berg"
#> ..$ rank : chr "Genus"
# search for genera within a family
search_wcvp(list(family="Myrtaceae"), filters=c("genera"))
#> <WCVP search: family='Myrtaceae' filters: 'genera'>
#> total results: 359
#> returned results: 50
#> total pages: 8
#> current page: 8
#> List of 1
#> $ :List of 10
#> ..$ id : chr "27387-1"
#> ..$ fqId : chr "urn:lsid:ipni.org:names:27387-1"
#> ..$ url : chr "/taxon/27387-1"
#> ..$ display : chr "<i>Abbevillea</i> O.Berg"
#> ..$ accepted : logi FALSE
#> ..$ synonymOf:List of 9
#> ..$ family : chr "Myrtaceae"
#> ..$ name : chr "Abbevillea"
#> ..$ author : chr "O.Berg"
#> ..$ rank : chr "Genus"
# search for all names with a specific epithet
search_wcvp(list(species="guianensis"))
#> <WCVP search: species='guianensis' filters: 'none'>
#> total results: 657
#> returned results: 50
#> total pages: 14
#> current page: 14
#> List of 1
#> $ :List of 9
#> ..$ id : chr "78925-2"
#> ..$ fqId : chr "urn:lsid:ipni.org:names:78925-2"
#> ..$ url : chr "/taxon/78925-2"
#> ..$ display : chr "<b><i>Dianthera guianensis</i> N.E.Br.</b>"
#> ..$ accepted: logi TRUE
#> ..$ family : chr "Acanthaceae"
#> ..$ name : chr "Dianthera guianensis"
#> ..$ author : chr "N.E.Br."
#> ..$ rank : chr "Species"
# search for a species name and print the results
r <- search_wcvp("Myrcia guianensis", filters=c("species"))
print(r)
#> <WCVP search: 'Myrcia guianensis' filters: 'species'>
#> total results: 1
#> returned results: 1
#> total pages: 1
#> current page: 1
#> List of 1
#> $ :List of 9
#> ..$ id : chr "598851-1"
#> ..$ fqId : chr "urn:lsid:ipni.org:names:598851-1"
#> ..$ url : chr "/taxon/598851-1"
#> ..$ display : chr "<b><i>Myrcia guianensis</i> (Aubl.) DC.</b>"
#> ..$ accepted: logi TRUE
#> ..$ family : chr "Myrtaceae"
#> ..$ name : chr "Myrcia guianensis"
#> ..$ author : chr "(Aubl.) DC."
#> ..$ rank : chr "Species"
# simplify search results to a `tibble`
r <- search_wcvp("Poa", filters=c("species"))
tidy(r)
#> # A tibble: 50 × 10
#> id fqId url display accepted family name author rank synonymOf
#> <chr> <chr> <chr> <chr> <lgl> <chr> <chr> <chr> <chr> <list>
#> 1 416409-1 urn:l… /taxo… <b><i>… TRUE Poace… Poa … R.Br. Spec… <NULL>
#> 2 416411-1 urn:l… /taxo… <i>Poa… FALSE Poace… Poa … Schur Spec… <tibble …
#> 3 416412-1 urn:l… /taxo… <i>Poa… FALSE Poace… Poa … R.Br. Spec… <tibble …
#> 4 322592-2 urn:l… /taxo… <i>Poa… FALSE Poace… Poa … Jacq. Spec… <tibble …
#> 5 416414-1 urn:l… /taxo… <b><i>… TRUE Poace… Poa … Bucha… Spec… <NULL>
#> 6 416415-1 urn:l… /taxo… <i>Poa… FALSE Poace… Poa … (Trin… Spec… <tibble …
#> 7 416416-1 urn:l… /taxo… <b><i>… TRUE Poace… Poa … É.Des… Spec… <NULL>
#> 8 70027705-1 urn:l… /taxo… <i>Poa… FALSE Poace… Poa … Keng … Spec… <tibble …
#> 9 204059-2 urn:l… /taxo… <i>Poa… FALSE Poace… Poa … Hack. Spec… <tibble …
#> 10 416418-1 urn:l… /taxo… <b><i>… TRUE Poace… Poa … Steud. Spec… <NULL>
#> # … with 40 more rows
# accepted name info is nested inside the records for synonyms
# simplify accepted name info to the name ID
r <- search_wcvp("Poa", filters=c("species"))
tidied <- tidy(r)
tidyr::unnest(tidied, cols=synonymOf, names_sep="_")
#> # A tibble: 27 × 18
#> id fqId url display accepted family name author rank synonymOf_id
#> <chr> <chr> <chr> <chr> <lgl> <chr> <chr> <chr> <chr> <chr>
#> 1 41641… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … Schur Spec… 204398-2
#> 2 41641… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … R.Br. Spec… 404736-1
#> 3 32259… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … Jacq. Spec… 1105499-2
#> 4 41641… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … (Trin… Spec… 322581-2
#> 5 70027… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … Keng … Spec… 320039-2
#> 6 20405… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … Hack. Spec… 77091513-1
#> 7 77107… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … (Olon… Spec… 416557-1
#> 8 41642… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … Ovcz. Spec… 417077-1
#> 9 41642… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … Ovcz.… Spec… 416668-1
#> 10 32257… urn:ls… /tax… <i>Poa … FALSE Poace… Poa … Kunth Spec… 1051970-2
#> # … with 17 more rows, and 8 more variables: synonymOf_fqId <chr>,
#> # synonymOf_url <chr>, synonymOf_display <chr>, synonymOf_accepted <lgl>,
#> # synonymOf_family <chr>, synonymOf_name <chr>, synonymOf_author <chr>,
#> # synonymOf_rank <chr>