This wiki gives information about the Global Biotic Interactions API. The goal of this API is to provide access to interaction data for the purpose of integrating the data into wikis, custom webpages or other interaction exploration tools. GoMexSI is an example of a website that is using this API. A javascript and R library use this API to facilitate access to interactions data.
| description | example |
|---|---|
| find all interactions in a square spatial region | Find all available interaction in a rectangular search area using bounding box or point as defined in [opensearch geo draft] (http://www.opensearch.org/Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2#The_.22box.22_parameter). For example : https://api.globalbioticinteractions.org/interaction?bbox=-67.87,12.79,-57.08,23.32 . Or, find all available interactions in rectangular area for specific source taxon (Actinopterygii) and target taxa (Arthropoda): https://api.globalbioticinteractions.org/interaction?bbox=-67.87,12.79,-57.08,23.32&sourceTaxon=Actinopterygii&targetTaxon=Arthropoda |
| find by interaction type | find all interactions Arthropod parasites with their Mammalian hosts https://api.globalbioticinteractions.org/interaction?sourceTaxon=Arthropoda&targetTaxon=Mammalia&interactionType=parasiteOf |
| find all locations at which interactions were observed | https://api.globalbioticinteractions.org/locations |
| list supported interaction types | https://api.globalbioticinteractions.org/interactionTypes |
| find distinct prey (or any other interaction type) of taxon | Find all predators of a rat (Rattus rattus): https://api.globalbioticinteractions.org/taxon/Rattus%20rattus/preyedUponBy . Or, find taxa that humans (Homo sapiens) prey on: https://api.globalbioticinteractions.org/taxon/Homo%20sapiens/eats |
| find distinct prey (or any other interaction type) of a specific taxonomic rank | Find all birds (Aves) that humans (Homo sapiens) eats: https://api.globalbioticinteractions.org/taxon/Homo%20sapiens/eats/Aves |
| find all interaction observations for a specific taxon | Find all predator observations that ate blue crab (Callinectes sapidus): https://api.globalbioticinteractions.org/taxon/Callinectes%20sapidus/preyedUponBy?includeObservations=true |
| find all interaction observations between specific taxa | Find all birds (Aves) that preyed on blue crab (Callinectes sapidus): https://api.globalbioticinteractions.org/taxon/Callinectes%20sapidus/preyedUponBy/Aves?includeObservations=true |
| description | examples |
|---|---|
| find close matches for available GloBI taxa by name | Find taxa that closely or loosely match (Homo SALIents): https://api.globalbioticinteractions.org/findCloseMatchesForTaxon/Homo%20SALIents. Or, find taxa that closely or loosely match (Mammelia), a misspelling of (Mammalia), a scientific term for describing mammals. https://api.globalbioticinteractions.org/findCloseMatchesForTaxon/Mammelia . Or even by common name: find taxa that closely match Mencsh, a misspelling of the (Mensch) the german common name for human or man. https://api.globalbioticinteractions.org/findCloseMatchesForTaxon/Mencsh |
| Find images for taxon id (e.g. eol page id) | https://api.globalbioticinteractions.org/images/NCBI:9606 |
| Find urls images of taxa | https://api.globalbioticinteractions.org/imagesForName/Homo%20sapiens |
| Find an url for taxon page for taxon | Find url to information about Brown Shrimp (Farfantepenaeus aztecus): https://api.globalbioticinteractions.org/findExternalUrlForTaxon/Farfantepenaeus%20aztecus |
| description | example |
|---|---|
| Find sources of GloBI interaction sets | https://api.globalbioticinteractions.org/reports/sources lists the sources that contributed datasets to GloBI |
| Find statistics of and references to GloBI interaction data sets | https://api.globalbioticinteractions.org/reports/studies optionally, you can select datasets of a particular data source like: https://api.globalbioticinteractions.org/reports/studies?source=http://gomexsi.tamucc.edu . |
| Find aggregates statistics of GloBI interaction data sets | https://api.globalbioticinteractions.org/reports/sources optionally, add the source like https://api.globalbioticinteractions.org/reports/sources?source=http://gomexsi.tamucc.edu to list aggregate statistics for a specific data source. |
| Find an url for info about a study by | Find url for study with title/ref Palacios Sanchez 2001: https://api.globalbioticinteractions.org/findExternalUrlForStudy/Palacios%20Sanchez%202001 |
Some query parameters are used to make specific requests related to return format, region of interest and/or taxa of interest. A query parameters is the stuff after the ? in the url. For instance, in https://api.globalbioticinteractions.org/taxon/Callinectes%20sapidus/preyedUponBy?includeObservations=true , the includeObservations=true is a query parameter. See Query String for more information.
The following return format are supported:
-
type=csv- returns results in tabular comma separated value (csv) format -
type=tsv- returns results in tabular tab separated value (tsv) format -
type=json- returns results in tabular json format: fairly compact notation because column/ property names aren't repeated, but harder to parse. -
type=json.v2- returns results in denormalized json format: not efficient notation when optimizing for result download speed, but easy to parse. -
type=dot- returns results in the dot language. Dot a is commonly used to visualize complex networks (like food webs!) using tools like GraphViz, Cytoscape, and Gephi.
You can specify the result type by setting type=csv, type=json, or type=json.v2 as a query parameters.
For example, url for requesting the list of the prey items of Homo sapiens in json.v2 format would look like: https://api.globalbioticinteractions.org/taxon/Homo%20sapiens/eats?type=json.v2 . A csv result format can would be more like: https://api.globalbioticinteractions.org/taxon/Homo%20sapiens/eats?type=csv&includeObservations=true . Using dot, you could visualize a food web near the Cayman Islands downloading the dot file using https://api.globalbioticinteractions.org/interaction?bbox=-82.203,17.077,-79.215,20.632&type=dot .
To ensure quick responses to requests, most operations support pagination. By default, the maximum amount of results (e.g. rows) returned is limited to 1024. You can control this by setting the limit and offset parameter in the request url. For instance, to retrieve the first 5 observations of predators eating the blue crab (Callinectes sapidus) use https://api.globalbioticinteractions.org/interaction?targetTaxon=Callinectes%20sapidus&limit=5 . Alternatively, you can retrieve the 5 following predators starting from the 6th predator using https://api.globalbioticinteractions.org/interaction?targetTaxon=Callinectes%20sapidus&offset=6&limit=5 .
For each of the observation or distinct interaction queries, you can add lat/lng (point) or [https://wiki.openstreetmap.org/wiki/Bounding_Box](bounding box) spatial search parameters. The former restricts by a specific point, the latter selects all locations with a bounding box of left (min Longitude) , bottom (min Latitude) , right (max Longitude) , and top (max Latitude) .
Find all distinct locations at which interactions have been observed: https://api.globalbioticinteractions.org/locations
Find all distinct prey of human (Homo sapiens) at exactly at latitude 39.76 and longitude -98.5: https://api.globalbioticinteractions.org/taxon/Homo%20sapiens/eats?lat=39.76&lng=-98.5
Find all available interaction at a specific latitude 18.24829 and longitude -66.49989: https://api.globalbioticinteractions.org/interaction?lat=18.24829&lng=-66.49989
Find all available interaction in a bounding box east of longitude -67.87, north of 12.79 latitude, west of -57.08 longitude, and south of longitude 23.32: https://api.globalbioticinteractions.org/interaction?bbox=-67.87,12.79,-57.08,23.32
Find all available interactions in rectangular area for specific source taxon (Octopus) and (Actinopterygii) target taxon (Arthropoda): https://api.globalbioticinteractions.org/interaction?bbox=-67.87,12.79,-57.08,23.32&sourceTaxon=Octopus&sourceTaxon=Actinopterygii&targetTaxon=Arthropoda
Find all available observed food items of hardhead catfish (Ariopsis felis) in a bounding box: https://api.globalbioticinteractions.org/taxon/Ariopsis%20felis/eats?includeObservations=true&bbox=-97.87,20.79,-95.08,30
Find all distinct consumers of brown shrimp (Farfantepenaeus aztecus) in a bounding box: https://api.globalbioticinteractions.org/taxon/Farfantepenaeus%20aztecus/eatenBy?bbox=-97.87,20.79,-95.08,30
Returned fields can be selected by using the field query parameters. For instance, if only the names of sea otter (Enhydra) predator and their prey names are of interest, the following URL will point to the desired result: https://api.globalbioticinteractions.org/interaction?interactionType=eats&sourceTaxon=Enhydra&field=source_taxon_name&field=target_taxon_name . For a list of supported return fields, see https://api.globalbioticinteractions.org/interactionFields .
The return fields can also be supplied by a fields query parameter. Rather than repeating the query parameter, a comma delimited list of request fields is provided: https://api.globalbioticinteractions.org/interaction?interactionType=eats&sourceTaxon=Enhydra&fields=source_taxon_name,target_taxon_name .
If only interactions from a specific data source or study are of interest, the parameter accordingTo can be used. The value of this parameter is used to include interactions that are provided by studies and/or data sources that contain the accordingTo value. For instance, the following url is used to selected interaction for only mammals (Mammalia) that were shared by inaturalist: https://api.globalbioticinteractions.org/interaction?sourceTaxon=Mammalia&accordingTo=inaturalist . If you'd like to include the fields study_source_citation, study_citation and study_external_id, make sure to specify the fields as well as the includeObservations=true query parameter (e.g. mammal interactions according to inaturalist w/ study, source fields) .
Note that when valid urls (e.g. http://www.inaturalist.org/observations/404096) are provided in the accordingTo parameter values, only results with exact study_url matches are returned. In this case, a valid url like http://inaturalist.org would return no matches, because no study has an external url with that exact same url. See https://github.com/globalbioticinteractions/globalbioticinteractions/issues/120#issuecomment-93155731 for context.
On inspecting API results, you'll often find things like EOL:1 or NCBI:9606. These strings refer to resources that are defined elsewhere: the former is defined at http://eol.org/pages/1, while the latter can be found at https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=9606 .
ID prefixes used within GloBI can be found at https://api.globalbioticinteractions.org/prefixes .
GloBI attempts to link taxonomic names with many kinds of taxonomies to enable linkages between systems (see Ecology of Data) and check for naming consistencies. By default, the api returns the first taxonomic term associated with interacting taxa. If you'd like favor one taxonomy, you can specify taxonIdPrefix=[some prefix] as part of your api request (related feature request). For example, if you'd like to retrieve a tab separated values file of sea otter parasites expressed in the Open Tree of Life, you'd request https://api.globalbioticinteractions.org/interaction?sourceTaxon=Enhydra%20lutris&interactionType=hasParasite&taxonIdPrefix=OTT&type=tsv . For a list of available taxon id prefixes, see https://api.globalbioticinteractions.org/prefixes .
By default, returned taxonomic (interaction) queries return the results related to the specified taxa (e.g. ray-finned fishes (Actinopterygii), birds (Aves)) and their child taxa (e.g. Atlantic Bluefin Tuna (Thunnus thynnus), ducks (Anas) resp.). To exclude child taxa results, the query parameter excludeChildTaxa=true can be specified. So, a question like "what do birds eat?" can be answered using https://api.globalbioticinteractions.org/interaction?sourceTaxon=Aves&interactionType=eats . If you'd like to disable this taxonomic inference (e.g. a duck is a kind of bird, to duck interaction are included), query would look something like: https://api.globalbioticinteractions.org/interaction?sourceTaxon=Aves&interactionType=eats&excludeChildTaxa=true . Now only interactions that explicitly state an interaction between specified taxa are included. In this example, ducks (Anas) will no longer appear in the result when this parameter is set.
List all the supported interaction types : https://api.globalbioticinteractions.org/interactionTypes
List all shortest paths that connect humans (Homo sapiens) with rats (Rattus rattus) in the species interaction graph/web: https://api.globalbioticinteractions.org/shortestPathsBetweenTaxon/Homo%20sapiens/andTaxon/Rattus%20rattus
Result containing "Homo sapiens", "Aves", "Diptera", "Rattus rattus" means that a shortest interaction paths from a human to a rat is: humans (Homo sapiens) interact with birds (Aves) who interact with true flies, mosquitoes and gnats (Diptera) who interact with rats (Rattus rattus) .
List all shortest paths that connect humans (Homo sapiens) and a marine isopod parasite (Cymothoa excisa) in the species interaction graph/web: https://api.globalbioticinteractions.org/shortestPathsBetweenTaxon/Homo%20sapiens/andTaxon/Cymothoa%20excisa
Note that interactions include predation, but also parasitic and other types of interactions.
Examples below return all distinct predator or prey of a specific taxon.
Find all distinct predators of rat (Rattus rattus): https://api.globalbioticinteractions.org/taxon/Rattus%20rattus/preyedUponBy
Find all distinct prey of humans (Homo sapiens): https://api.globalbioticinteractions.org/taxon/Homo%20sapiens/preysOn
Find all prey items classified as birds (Aves) of humans (Homo sapiens): https://api.globalbioticinteractions.org/taxon/Homo%20sapiens/preysOn/Aves
Examples below return all observed interaction with predator or prey of a specific taxon.
Find all predator observations that ate blue crab (Callinectes sapidus): https://api.globalbioticinteractions.org/taxon/Callinectes%20sapidus/preyedUponBy?includeObservations=true
Find all observations of humans (Homo sapiens) that ate birds (Aves): https://api.globalbioticinteractions.org/taxon/Homo%20sapiens/preysOn/Aves?includeObservations=true
Find prey for observations of predator hardhead catfish (Ariopsis felis): https://api.globalbioticinteractions.org/taxon/Ariopsis%20felis/preysOn?includeObservations=true
or even:
Find urls that point to images for taxon with external id ITIS:173833: https://api.globalbioticinteractions.org/images/ITIS:173833
Find urls that point to images for taxon with name: https://api.globalbioticinteractions.org/imagesForName/Homo%20sapiens
Find an url that points to an overview page of brown shrimp (Farfantepenaeus aztecus): https://api.globalbioticinteractions.org/findExternalUrlForTaxon/Farfantepenaeus%20aztecus
Find an url that points to an overview page of taxon with external id ITIS:173833: https://api.globalbioticinteractions.org/findExternalUrlForExternalId/ITIS:173833
Retrieve a list containing information about the contributors to GloBI: https://api.globalbioticinteractions.org/contributors
Retrieve an externalUrl for studies associated to a study with title/ref Palacios Sanchez 2001:
https://api.globalbioticinteractions.org/findExternalUrlForStudy/Palacios%20Sanchez%202001
where Palacios%20Sanchez%202001is the study title reference used in url encoding.
returns:
{"url":"http://research.myfwc.com/game/Survey.aspx?id=2969"}
when no study matches or no url is available, an empty json object, {}, is returned.
Find taxa that closely or loosely match (Homo SALIents): https://api.globalbioticinteractions.org/findCloseMatchesForTaxon/Homo%20SALIents
Find taxa that closely or loosely match (Mammelia), a misspelling of (Mammalia), a scientific term for describing mammals. https://api.globalbioticinteractions.org/findCloseMatchesForTaxon/Mammelia
Find taxa that closely match Mencsh, a misspelling of the (Mensch) the german common name for human or man. https://api.globalbioticinteractions.org/findCloseMatchesForTaxon/Mencsh
