Query Plants of the World Online for taxon information.

search_powo(query, filters = NULL, cursor = NULL, limit = 50, .wait = 0.2)

Arguments

query

The string to query POWO with. If using keywords, the query must be formatted as a list.

filters

Filter to apply to search results. Multiple filters must be supplied as a character vector.

cursor

A cursor returned by a previous search. If used, the query and filter must be exactly the same.

limit

The maximum number of records to return.

.wait

Time to wait before making a request, to help rate limiting.

Value

Returns an object of class powo_search that is a simple structure with slots for:

  • total: the total number of results held in POWO for the query

  • pages: the total number of results pages for the query.

  • limit: the maximum number of results requested from the API, per page.

  • cursor: a cursor to retrieve the next page of results from the API.

  • results: the query results parsed into a list.

  • query: the query string submitted to the API.

  • response: the httr response object.

Details

Plants of the World Online (POWO) is a database of information on the world's flora. It curates information from published floras and other sources of floristic information.

The search API allows users to query the database using plant names, geographic terms, and floristic characters. These can be queried using keyword arguments. Use the get_keywords function for a list of all implemented keywords.

The API returns taxonomic information as well as species descriptions and image locations if available. These results can be limited, for example to accepted species, using filters. Use the get_filters function to get a list of all implemented filters.

Distributions in POWO are categorised using the World Geographical Scheme for Recording Plant Distributions (WGSRP). Users can query POWO using distributions listed under WGSRPD levels 1 (continents), 2 (regions), and 3 (botanical countries).

See also

Other POWO functions: lookup_powo()

Examples

# search for all entries containing a genus name
search_powo("Myrcia")
#> <POWO search: 'Myrcia' filters: 'none'>
#> total results: 1402
#> returned results: 50
#> total pages: 29
#> First result:
#> List of 1
#>  $ :List of 10
#>   ..$ accepted: logi TRUE
#>   ..$ author  : chr "(D.Legrand) NicLugh."
#>   ..$ kingdom : chr "Plantae"
#>   ..$ family  : chr "Myrtaceae"
#>   ..$ name    : chr "Myrcia catharinensis"
#>   ..$ rank    : chr "Species"
#>   ..$ snippet : chr " <b>General</b>: <em>Myrcia</em> catharinensis is recognised by its rather narrow<br/> <b>Flower</b>: <em>Myrci"| __truncated__
#>   ..$ url     : chr "/taxon/urn:lsid:ipni.org:names:77118654-1"
#>   ..$ fqId    : chr "urn:lsid:ipni.org:names:77118654-1"
#>   ..$ images  :List of 1

# search for all accepted species within a genus
search_powo("Myrcia", filters=c("species", "accepted"))
#> <POWO search: 'Myrcia' filters: 'species, accepted'>
#> total results: 767
#> returned results: 50
#> total pages: 16
#> First result:
#> List of 1
#>  $ :List of 10
#>   ..$ accepted: logi TRUE
#>   ..$ author  : chr "(D.Legrand) NicLugh."
#>   ..$ kingdom : chr "Plantae"
#>   ..$ family  : chr "Myrtaceae"
#>   ..$ name    : chr "Myrcia catharinensis"
#>   ..$ rank    : chr "Species"
#>   ..$ snippet : chr " <b>General</b>: <em>Myrcia</em> catharinensis is recognised by its rather narrow<br/> <b>Flower</b>: <em>Myrci"| __truncated__
#>   ..$ url     : chr "/taxon/urn:lsid:ipni.org:names:77118654-1"
#>   ..$ fqId    : chr "urn:lsid:ipni.org:names:77118654-1"
#>   ..$ images  :List of 1

# search for up to 100 species in a genus
search_powo("Poa", filters=c("species"), limit=100)
#> <POWO search: 'Poa' filters: 'species'>
#> total results: 2003
#> returned results: 100
#> total pages: 21
#> First result:
#> List of 1
#>  $ :List of 10
#>   ..$ accepted : logi FALSE
#>   ..$ author   : chr "(Lam. & DC.) Chevall."
#>   ..$ kingdom  : chr "Plantae"
#>   ..$ family   : chr "Poaceae"
#>   ..$ name     : chr "Agropyron poa"
#>   ..$ rank     : chr "Species"
#>   ..$ snippet  : chr " <b>Species</b>: <em>poa</em>"
#>   ..$ synonymOf:List of 5
#>   ..$ url      : chr "/taxon/urn:lsid:ipni.org:names:385169-1"
#>   ..$ fqId     : chr "urn:lsid:ipni.org:names:385169-1"

# search for all names in a family
search_powo(list(family="Myrtaceae"))
#> <POWO search: family='Myrtaceae' filters: 'none'>
#> total results: 17601
#> returned results: 50
#> total pages: 353
#> First result:
#> List of 1
#>  $ :List of 9
#>   ..$ accepted: logi TRUE
#>   ..$ author  : chr "Juss."
#>   ..$ kingdom : chr "Plantae"
#>   ..$ family  : chr "Myrtaceae"
#>   ..$ name    : chr "Myrtaceae"
#>   ..$ rank    : chr "Family"
#>   ..$ url     : chr "/taxon/urn:lsid:ipni.org:names:30000056-2"
#>   ..$ fqId    : chr "urn:lsid:ipni.org:names:30000056-2"
#>   ..$ images  :List of 3

# search for all accepted species with blue flowers
search_powo(list(flower="blue"), filters=c("accepted", "species"))
#> <POWO search: flower='blue' filters: 'accepted, species'>
#> total results: 1270
#> returned results: 50
#> total pages: 26
#> First result:
#> List of 1
#>  $ :List of 10
#>   ..$ accepted: logi TRUE
#>   ..$ author  : chr "(Hook.f.) Jacq.-Fél."
#>   ..$ kingdom : chr "Plantae"
#>   ..$ family  : chr "Melastomataceae"
#>   ..$ name    : chr "Warneckea membranifolia"
#>   ..$ rank    : chr "Species"
#>   ..$ snippet : chr " <b>Flower</b>: Filaments vivid <em>blue</em>"
#>   ..$ url     : chr "/taxon/urn:lsid:ipni.org:names:576916-1"
#>   ..$ fqId    : chr "urn:lsid:ipni.org:names:576916-1"
#>   ..$ images  :List of 1

# search for all accepted genera in Mexico
search_powo(list(distribution="Mexico"), filters=c("accepted", "genera"))
#> <POWO search: distribution='Mexico' filters: 'accepted, genera'>
#> total results: 2994
#> returned results: 50
#> total pages: 60
#> First result:
#> List of 1
#>  $ :List of 9
#>   ..$ accepted: logi TRUE
#>   ..$ author  : chr "J.T.Howell"
#>   ..$ kingdom : chr "Plantae"
#>   ..$ family  : chr "Asteraceae"
#>   ..$ name    : chr "Baeriopsis"
#>   ..$ rank    : chr "Genus"
#>   ..$ snippet : chr " <b>Location</b>: <em>Mexico</em>"
#>   ..$ url     : chr "/taxon/urn:lsid:ipni.org:names:298120-2"
#>   ..$ fqId    : chr "urn:lsid:ipni.org:names:298120-2"

# search for a species name and print the results
r <- search_powo("Myrcia guianensis", filters=c("species"))
print(r)
#> <POWO search: 'Myrcia guianensis' filters: 'species'>
#> total results: 1
#> returned results: 1
#> total pages: 1
#> First result:
#> List of 1
#>  $ :List of 9
#>   ..$ accepted: logi TRUE
#>   ..$ author  : chr "(Aubl.) DC."
#>   ..$ kingdom : chr "Plantae"
#>   ..$ family  : chr "Myrtaceae"
#>   ..$ name    : chr "Myrcia guianensis"
#>   ..$ rank    : chr "Species"
#>   ..$ url     : chr "/taxon/urn:lsid:ipni.org:names:598851-1"
#>   ..$ fqId    : chr "urn:lsid:ipni.org:names:598851-1"
#>   ..$ images  :List of 3

# simplify search results to a `tibble`
r <- search_powo("Poa", filters=c("species"))
tidy(r)
#> # A tibble: 50 × 11
#>    accepted author  kingdom family  name   rank  snippet   synonymOf url   fqId 
#>    <lgl>    <chr>   <chr>   <chr>   <chr>  <chr> <chr>     <list>    <chr> <chr>
#>  1 FALSE    (Lam. … Plantae Poaceae Agrop… Spec… " <b>Spe… <tibble … /tax… urn:…
#>  2 FALSE    Nees e… Plantae Poaceae Briza… Spec… " <b>Spe… <tibble … /tax… urn:…
#>  3 FALSE    Stapf   Plantae Poaceae Eragr… Spec… " <b>Spe… <tibble … /tax… urn:…
#>  4 FALSE    (Lam. … Plantae Poaceae Festu… Spec… " <b>Spe… <tibble … /tax… urn:…
#>  5 FALSE    (Lam. … Plantae Poaceae Nardu… Spec… " <b>Spe… <tibble … /tax… urn:…
#>  6 FALSE    Lam. &… Plantae Poaceae Triti… Spec… " <b>Spe… <tibble … /tax… urn:…
#>  7 TRUE     (L.) W… Plantae Caprif… Valer… Spec… " <b>Gen… <NULL>    /tax… urn:…
#>  8 TRUE     L.      Plantae Primul… Andro… Spec… " <b>Gen… <NULL>    /tax… urn:…
#>  9 TRUE     R.Br.   Plantae Poaceae Poa a… Spec…  NA       <NULL>    /tax… urn:…
#> 10 FALSE    Schur   Plantae Poaceae Poa a… Spec…  NA       <tibble … /tax… urn:…
#> # … with 40 more rows, and 1 more variable: images <list>