Query the International Plant Names Index for nomenclatural information.
search_ipni(query, filters = NULL, cursor = "*", limit = 50, .wait = 0.1)
The string to query IPNI with. If using keywords, the query must be formatted as a list.
Filter to apply to search results.
A cursor returned by a previous search. If used, the query and filter must be exactly the same.
The maximum number of records to return. This has a maximum of 1000.
Time to wait before making a request, to help rate limiting.
Returns an object of class ipni_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.
The International Plant Names Index (IPNI) is a service that provides nomenclatural information for vascular plant names.
The search API allows users to query the database for plant names, as well as authors and publications. There may be limited support for some sort of fuzzy matching.
There is some support for querying using keyword arguments. Documentation for
the API is currently available in the pykew
package,
so keywords have been copied across from there. There are sets of keywords
relating to plants, authors, and publications. A full list of keywords can be viewed
using the get_keywords
function.
The API will return nomenclatural information (publication date, nomenclatural status, author, etc.)
of all names matching the query. These results can be limited, for example to only family names,
using filters. Use the get_filters
function to get a list of all implemented filters.
lookup_ipni()
to look up a name using an IPNI ID.
Other IPNI functions:
lookup_ipni()
# search for all names containing Poa annua
results <- search_ipni("Poa annua")
#> No encoding supplied: defaulting to UTF-8.
# tidy search results in a table
tidy(results)
#> # A tibble: 13 × 45
#> name authors publishingAuthor authorTeam rank url family genus species
#> <chr> <chr> <chr> <list> <chr> <chr> <chr> <chr> <chr>
#> 1 Poa an… L. L. <tibble [… spec. /n/3… Poace… Poa annua
#> 2 Poa an… Steud. Steud. <tibble [… spec. /n/4… Poace… Poa annua
#> 3 Poa an… Cham. &… Cham. & Schltdl. <tibble [… spec. /n/4… Poace… Poa annua
#> 4 Poa an… É.Desv. É.Desv. <tibble [… var. /n/2… Poace… Poa annua
#> 5 Poa an… Wall. e… Wall. ex Griseb. <tibble [… var. /n/6… Poace… Poa annua
#> 6 Poa an… Chrtek … Chrtek & V.Jirá… <tibble [… subs… /n/7… Poace… Poa annua
#> 7 Poa an… Ronniger Ronniger <tibble [… var. /n/7… Poace… Poa annua
#> 8 Poa an… (Ronnig… H.Scholz <tibble [… subs… /n/7… Poace… Poa annua
#> 9 Poa an… Mike L.… Mike L.Grant <tibble [… f. /n/7… Poace… Poa annua
#> 10 Poa an… (S.E.Fr… Chrtek <tibble [… subs… /n/1… Poace… Poa annua
#> 11 Poa an… S.E.Frö… S.E.Fröhner <tibble [… var. /n/5… Poace… Poa annua
#> 12 Poa an… (Haussk… T.Koyama <tibble [… f. /n/9… Poace… Poa annua
#> 13 Poa an… L.H.Dew… L.H.Dewey <tibble [… var. /n/2… Poace… Poa annua
#> # … with 36 more variables: citationType <chr>, hybrid <lgl>,
#> # hybridGenus <lgl>, inPowo <lgl>, linkedPublication <list>,
#> # publication <chr>, publicationYear <int>, publicationYearNote <chr>,
#> # referenceCollation <chr>, publicationId <chr>, recordType <chr>,
#> # reference <chr>, remarks <chr>, suppressed <lgl>, topCopy <lgl>,
#> # typeLocations <chr>, version <chr>, id <chr>, fqId <chr>,
#> # hasNomenclaturalNotes <lgl>, hasTypeData <lgl>, hasOriginalData <lgl>, …
# extract author team information for the search results
results_tbl <- tidy(results)
tidyr::unnest(results_tbl, cols=c(authorTeam), names_sep="_")
#> # A tibble: 19 × 50
#> name authors publishingAuthor authorTeam_name authorTeam_id authorTeam_order
#> <chr> <chr> <chr> <chr> <chr> <int>
#> 1 Poa … L. L. L. 12653-1 0
#> 2 Poa … Steud. Steud. Steud. 10122-1 1
#> 3 Poa … Cham. … Cham. & Schltdl. Schltdl. 9114-1 2
#> 4 Poa … Cham. … Cham. & Schltdl. Cham. 1504-1 1
#> 5 Poa … É.Desv. É.Desv. É.Desv. 2160-1 1
#> 6 Poa … Wall. … Wall. ex Griseb. Wall. 12990-1 1
#> 7 Poa … Wall. … Wall. ex Griseb. Griseb. 3397-1 2
#> 8 Poa … Chrtek… Chrtek & V.Jirá… Chrtek 1637-1 1
#> 9 Poa … Chrtek… Chrtek & V.Jirá… V.Jirásek 4492-1 2
#> 10 Poa … Ronnig… Ronniger Ronniger 8572-1 1
#> 11 Poa … (Ronni… H.Scholz Ronniger 8572-1 2
#> 12 Poa … (Ronni… H.Scholz H.Scholz 9229-1 1
#> 13 Poa … Mike L… Mike L.Grant Mike L.Grant 20000154-1 1
#> 14 Poa … (S.E.F… Chrtek S.E.Fröhner 2933-1 1
#> 15 Poa … (S.E.F… Chrtek Chrtek 1637-1 2
#> 16 Poa … S.E.Fr… S.E.Fröhner S.E.Fröhner 2933-1 1
#> 17 Poa … (Hauss… T.Koyama T.Koyama 5003-1 2
#> 18 Poa … (Hauss… T.Koyama Hausskn. 3732-1 1
#> 19 Poa … L.H.De… L.H.Dewey L.H.Dewey 2178-1 0
#> # … with 44 more variables: authorTeam_type <chr>, authorTeam_summary <lgl>,
#> # authorTeam_url <chr>, rank <chr>, url <chr>, family <chr>, genus <chr>,
#> # species <chr>, citationType <chr>, hybrid <lgl>, hybridGenus <lgl>,
#> # inPowo <lgl>, linkedPublication <list>, publication <chr>,
#> # publicationYear <int>, publicationYearNote <chr>, referenceCollation <chr>,
#> # publicationId <chr>, recordType <chr>, reference <chr>, remarks <chr>,
#> # suppressed <lgl>, topCopy <lgl>, typeLocations <chr>, version <chr>, …
# filter results to only species names
species_results <- search_ipni("Poa annua", filters="species")
#> No encoding supplied: defaulting to UTF-8.
tidy(species_results)
#> # A tibble: 3 × 34
#> name authors publishingAuthor authorTeam rank url family genus species
#> <chr> <chr> <chr> <list> <chr> <chr> <chr> <chr> <chr>
#> 1 Poa annua L. L. <tibble [… spec. /n/3… Poace… Poa annua
#> 2 Poa annua Steud. Steud. <tibble [… spec. /n/4… Poace… Poa annua
#> 3 Poa annua Cham. … Cham. & Schltdl. <tibble [… spec. /n/4… Poace… Poa annua
#> # … with 25 more variables: citationType <chr>, hybrid <lgl>,
#> # hybridGenus <lgl>, inPowo <lgl>, linkedPublication <list>,
#> # publication <chr>, publicationYear <int>, publicationYearNote <chr>,
#> # referenceCollation <chr>, publicationId <chr>, recordType <chr>,
#> # reference <chr>, remarks <chr>, suppressed <lgl>, topCopy <lgl>,
#> # typeLocations <chr>, version <chr>, id <chr>, fqId <chr>,
#> # hasNomenclaturalNotes <lgl>, hasTypeData <lgl>, hasOriginalData <lgl>, …
# search for species from Mexico published in 1989
q <- list(published="1989", distribution="Mexico")
f <- "species"
results <- search_ipni(q, filters=f)
#> No encoding supplied: defaulting to UTF-8.
tidy(results)
#> # A tibble: 50 × 40
#> name authors publishingAuthor authorTeam rank url family genus species
#> <chr> <chr> <chr> <list> <chr> <chr> <chr> <chr> <chr>
#> 1 Abies… Rushfort… Rushforth & Nar… <tibble [… spec. /n/2… Pinac… Abies colime…
#> 2 Abies… Rushforth Rushforth <tibble [… spec. /n/2… Pinac… Abies flinck…
#> 3 Acour… L.Cabrera L.Cabrera <tibble [… spec. /n/2… Aster… Acou… dierin…
#> 4 Aesch… Rudd Rudd <tibble [… spec. /n/2… Fabac… Aesc… lyonne…
#> 5 Agari… L.M.Gonz… L.M.González <tibble [… spec. /n/2… Erica… Agar… villar…
#> 6 Agera… B.L.Turn… B.L.Turner <tibble [… spec. /n/2… Aster… Ager… chazar…
#> 7 Agera… B.L.Turn… B.L.Turner <tibble [… spec. /n/2… Aster… Ager… chimal…
#> 8 Agera… B.L.Turn… B.L.Turner <tibble [… spec. /n/2… Aster… Ager… perezii
#> 9 Arceu… (Hawksw.… Hawksw. & Wiens <tibble [… spec. /n/2… Visca… Arce… durang…
#> 10 Arceu… Hawksw. … Hawksw. & Wiens <tibble [… spec. /n/2… Visca… Arce… oaxaca…
#> # … with 40 more rows, and 31 more variables: citationType <chr>,
#> # collectionNumber <chr>, collectorTeam <chr>, distribution <chr>,
#> # hybrid <lgl>, hybridGenus <lgl>, inPowo <lgl>, linkedPublication <list>,
#> # publication <chr>, publicationYear <int>, referenceCollation <chr>,
#> # publicationId <chr>, recordType <chr>, reference <chr>, suppressed <lgl>,
#> # topCopy <lgl>, typeLocations <chr>, version <chr>, id <chr>, fqId <chr>,
#> # hasNomenclaturalNotes <lgl>, hasTypeData <lgl>, hasOriginalData <lgl>, …
# search for an author by surname
author_results <- search_ipni(list(author_surname="Gardiner"))
#> No encoding supplied: defaulting to UTF-8.
tidy(author_results)
#> # A tibble: 2 × 19
#> alternativeNames dates examples forename fqId id isoCountries recordType
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 "" 1981- Vanda lo… Lauren … urn:… 2001… "" author
#> 2 "" 1808-… NA William urn:… 3024… "United Kin… author
#> # … with 11 more variables: source <chr>, standardForm <chr>, surname <chr>,
#> # suppressed <lgl>, taxonGroups <chr>, url <chr>, version <chr>,
#> # summary <chr>, hasBhlLink <lgl>, alternativeAbbreviations <chr>,
#> # bhlPageLink <chr>