Query the International Plant Names Index for nomenclatural information.

search_ipni(query, filters = NULL, cursor = "*", limit = 50, .wait = 0.1)

Arguments

query

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

filters

Filter to apply to search results.

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. This has a maximum of 1000.

.wait

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

Value

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.

Details

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.

See also

Other IPNI functions: lookup_ipni()

Examples

# 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>