Queries in the API

Pierre Denelle & Patrick Weigelt

2023-03-14


This vignette shows how to work with the API, how it is related to the GIFT R package, and how are the R functions of the package interdependent.


API

The API endpoint is https://gift.uni-goettingen.de/api/extended/index.php. We then have different queries, listed in the table below, that allow retrieving distinct tables. The name in the column Query of the table below has to be used as the query argument. As an example, here is the query leading to the metadata table of the environmental rasters:
https://gift.uni-goettingen.de/api/extended/index.php?query=env_raster


Please note that the endpoint changes depending on the GIFT version you ask for. For example, with the same table as above, we can retrieve the table as it was in GIFT version 2.0:
https://gift.uni-goettingen.de/api/extended/index2.0.php?query=env_raster


While for this API there is no authentication needed, there is a password-protected API leading to some restricted content in the different tables. Restricted content can for example be some checklists which need the approval of their provider before being used. This API can be communicated upon request.


Here is the list of the 24 available queries, their arguments and in which GIFT R function they are called. There is no rate-limitation for any of these queries except species and phylogeny which retrieved the data into chunks.

Query Arguments R_function
checklists listid (integer) , taxonid, namesmatched, filter GIFT_checklists_raw()
env_misc GIFT_env_meta_misc()
env_raster GIFT_env_meta_raster()
geoentities_env_misc envvar GIFT_env()
geoentities_env_raster layername, sumstat GIFT_env()
lists GIFT_lists(), GIFT_checklists_conditional(), GIFT_checklists()
names_matched genus, epithet GIFT_species_lookup()
names_matched_unique genus, epithet GIFT_species_lookup()
overlap taxon, startat GIFT_species_distribution(), GIFT_no_overlap(), GIFT_checklists()
overlap_misc layer GIFT_overlap()
phylogeny taxon, startat, limit GIFT_phylogeny()
references_citavi GIFT_env_meta_raster(), GIFT_env_meta_misc()
references GIFT_references()
reference_traits GIFT_traits_raw()
regions GIFT_regions()
species startat, limit GIFT_species()
species_distr nameid GIFT_species_distribution()
species_num taxonid GIFT_richness()
taxonomy GIFT_taxonomy(), GIFT_taxgroup(), GIFT_richness(), GIFT_checklists_raw(), GIFT_checklists(), GIFT_checklists_conditional()
traits traitid, biasref, biasderiv, startat, limit GIFT_traits()
traits_cov traitid, taxonid GIFT_richness()
traits_meta GIFT_traits_meta()
traits_raw traitid, deriv, biasderiv, refid GIFT_traits_raw()
versions All GIFT functions


Some more details:

# Query for trait and chunks
# Default value for end is 10000
# https://gift.uni-goettingen.de/api/extended/index.php?query=traits&
# traitid=1.1.1&biasref=1&biasderiv=1&startat=100000&limit=10

# To retrieve the geojson
paste0("https://gift.uni-goettingen.de/geojson/geojson_smaller", 
       ifelse(GIFT_version == "beta", "", GIFT_version), "/",
       entity_ID[i], ".geojson")

Dependency graph of R functions

Dependency graph of the main functions of the package:

References

Weigelt, P., König, C., & Kreft, H. (2020). GIFT – A Global Inventory of Floras and Traits for macroecology and biogeography. Journal of Biogeography, 47(1), 16–43.