Thomas edited this page Feb 27, 2018 · 38 revisions

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.

Table of Contents

Interactions

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

Taxon Convenience Methods

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/EOL:327955
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

References to datasets

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

Query parameters

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.

Result Format

The following return format are supported:

  1. type=csv - returns results in tabular comma separated value (csv) format
  2. type=tsv - returns results in tabular tab separated value (tsv) format
  3. type=json - returns results in tabular json format: fairly compact notation because column/ property names aren't repeated, but harder to parse.
  4. type=json.v2 - returns results in denormalized json format: not efficient notation when optimizing for result download speed, but easy to parse.
  5. 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 .

Pagination

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 .

Spatial Query Parameters

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

Selecting return fields

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 .

Selecting specific studies or sources

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/jhpoelen/eol-globi-data/issues/120#issuecomment-93155731 for context.

ID Prefixes

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 .

Selecting specific taxonomies

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 .

Excluding child taxa

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.

More Examples

Interactions

Supported Interaction Types

List all the supported interaction types : https://api.globalbioticinteractions.org/interactionTypes

Shortest paths

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.

Distinct Taxa 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

Individual Interaction Observations (low level of detail)

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

CSV Raw data query

https://api.globalbioticinteractions.org/taxon/Rattus%20rattus/preyedUponBy?type=csv&includeObservations=true

or even:

https://api.globalbioticinteractions.org/taxon/Ariopsis%20felis/preysOn?includeObservations=true&bbox=-67.87,12.79,-57.08,23.32&type=csv

Taxon Information (images, overview pages, taxon name lookup)

Find urls that point to images on eol for taxon with external id EOL:276287: https://api.globalbioticinteractions.org/images/EOL:276287

Find urls that point to images on eol 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 EOL:344212: https://api.globalbioticinteractions.org/findExternalUrlForExternalId/EOL:344212

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.

Fuzzy search on scientific taxonomic ranks

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

Fuzzy search on common names

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

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.