R package to access the World Flora Online GraphQL API

2025-11-03

I have been working on integrating the WorldFlora R package into SEOSAW so we can use the World Flora Online taxonomic backbone to match taxonomic names in our tree inventory data. In doing this work I have learned that: a) the WorldFlora R package has some drawbacks, namely that it requires a large download of a static version of the WFO database, which also then needs to be read into memory in R, and b) that the WFO has a GraphQL API to access their database remotely without downloading the entire thing.

I have since developed a prototype R package which uses the API to return information from the WFO database, and contains functions for matching taxonomic names.

The package can be found here: https://github.com/johngodlee/wfoAPI

The top-level function is matchNames(), which takes a vector of taxonomic names and queries the WFO database for each name. Notable features of the function are:

callAPI() is the base-level function which constructs the API query and uses the httr2 package to send the query and unpack the returns.

matchName() calls callAPI() and is responsible for handling a single name query. matchName() optionally uses cached data from previous API calls if it exists. If multiple candidate names are matched, the user can optionally enter an interactive selection mode, which is handled by pickName().

matchNames() calls matchName() for each name in the vector of taxonomic names, performs various quality-of-life checks like exiting gracefully if the WFO API is not reachable, and formats the results as a pretty dataframe with one row for each name in the original vector.

These are the arguments available for matchNames():

fallbackToGenus, checkRank, checkHomonyms and fuzzyNameParts are all variables passed directly to the WFO GraphQL API.

Here is a basic example:

x <- c(
  "Burkea africana", 
  "Julbernardia paniculata", 
  "Fabaceae", 
  "Indet indet", 
  "Brachystegia",
  "Philenoptera sp.") 

matchNames(x)

The console output:

1 of 6: Brachystegia
2 of 6: Burkea africana
3 of 6: Fabaceae
4 of 6: Indet indet
No candidates, skipping: Indet indet
5 of 6: Julbernardia paniculata
6 of 6: Philenoptera sp.


--- Pick a name ---
Matching string:        Philenoptera sp.
1   wfo-4000029211      Philenoptera Hochst. ex A.Rich. accepted        Code/Plantae/Pteridobiotina/Angiosperms/Fabales/Fabaceae/Papilionoideae/Philenoptera

[ins] Enter a number to pick a row from the list, a valid WFO ID, 'N' for the next page, 'P' for the previous page, 'S' to skip this name:

The dataframe returned, formatted as a nested list for readability: