API Documentation¶
Note
These instructions cover the programmatic usage of the EarthLife Consortium RESTful API version 1. All requests will include /api_v1 in the base path and use the HTTP GET protocol.
An interactive web-based sandbox is available for exploring the API. The API can, of course be called directly using a browser, cURL or using your favorite HTTP library such as Requests. The generated query URL is available in the sandbox for copying and editing.
Occurrences¶
Occurrences are the individual instances of fossils in time and space. Occurrences of taxa can be specified at any taxonomic level bound by any units of time and spatial delimitation.
- Base path
http://earthlifeconsortium.org/api_v1/occ?
Parameters
taxon=taxon_name|genus+species- A single name or comma-separated list of taxa at any taxonomic level or a 2-3 word pair referring to a single species. As spaces are not allowed in HTTP URLs, the taxon names must be connected by a “+” symbol or a “%20” escape sequence. Type: str.
Note
Paleobiology Database: Taxonomic names returned by the Paleobiology Database reflect synonymies as entered from the published scientific literature and are dynamically updated. Documentation of the Paleobiology Database data model is provided by Peters, S.E. and McClennen, M., 2016. The Paleobiology Database application programming interface. Paleobiology, 42(1), pp.1-7.
Neotoma: Taxonomic names returned by the Neotoma databases reflect a static taxonomy as determined by taxonomic experts. Details of these determinations can be found here.
ELC API returns for any given taxon will include each database’s understanding of what is contained in the given taxon. If the taxonomic name does NOT occur in the given database, the ELC API will not return any data from that database. These two taxonomic concepts may not be the same in each included database.
bbox=POLYGON((...))- Geographic bounding box for constraining the response. Must be a strictly formatted OGC WKT Polygon. The unaffiliated tool OpenStreetMap WKT Playground may be useful in graphically creating a polygon. Paste the generated WKT string into the
bboxfield of the ELC API. Type: str
agerange=geologic_age,[value,value][geologic_age|value]- A single named geologic age or a comma-separated pair of numerical ages, geologic ages or a combination of the two. Order does not matter, returned ages will always reflect the minimum and maximum from the pairwise set. Type: str or float
Note
At a minimum, a taxon, bbox or agerange parameter must be specified, however more than one of these may be used together to further constrain the query.’
ageunits=ybp|ka|ma- Units of geologic age to be used in the query. Age values passed to the API will be interpreted in the context of this parameter. All time specific returned values will also be converted to match this parameter. Type: str. Default: “Ma”
coordtype=modern|paleo- Configure the type of cartesian coordinates to be included in the response. Most resource databases will store the geography of occurrences and other data objects using modern day coordinates. However, with some limitations (see
misc/paleocoordinatesroute below) the API is able to convert the coordinates in to a historical projection. Type: str. Default: “modern”
includelower=true|false- Include all species and subspecies of a named genera in the response. For PBDB the taxonomy system is used, for other databases, this flag triggers wildcard completion. This works well for species epithets but not for higher level taxa. Type: boolean. Default: “true”
limit=value- Impose a limit on the number of records returned from each database. Useful for testing or in conjuction with the
offsetparameter. Set to a very large number to negate any default limits set on any of the subqueried database resources. Type: int. Default: “999999”
offset=value- Select a sequential record number to begin the return. Useful in conjunction with
limitto chunk very large returns. For example,?limit=1000&offset=0would return the first 1000 records and?limit=1000&offset=1000the next 1000 records. Handling of this is specific to the resource database and has no relationship of any data record number, merely a database table row. If not included, the response will always begin with the first record. Type: int
output=json|csv- File format of the data return. Serialized JSON or tabular CSV. The meta-data block is a separate JSON object and thus is not included in the CSV file. The file name of the CSV file will include a shortened MD5 hash of the response data for identification purposes. Type: str. Default: “json”
show=all|poll|idxConfigure the objects to be included in the return. This parameter is ignored if the selected output format is “csv”. Type: str. Default: “all”
all: All data records and meta-datapoll: Only the meta-data block with summary statisticsidx: A list of the endpoints primary data indicies
run=all|database_name[,database_name, ...]- Single or comma separated list of resource databases for the API to query. Type: str. Default: “all”
Examples
See also
Find number of occurrences of the paleo-programmer’s best friend in each resource database:
http://earthlifeconsortium.org/api_v1/occ?taxon=canis+dirus
Retrieve first 10 occurrences of Pinus with ages reported as years before present:
http://earthlifeconsortium.org/api_v1/occ?taxon=pinus&limit=10&ageunits=ybp&includelower=false
Download all of the whales as tabular data:
http://earthlifeconsortium.org/api_v1/occ?taxon=cetacea&output=csv
Locales¶
A locale is a cube of time-space delimited with geographic units and geologic time bounds.
- Base path
http://earthlifeconsortium.org/api_v1/loc?
Parameters
idlist=database:datatype:id_number,[...]- Comma separated list of database specific ID numbers in the ELC extended format:
database: Subquery database name. Only first four characters are read so, for example, either “neot” or “neotoma” may be useddatatype: Short name for the data object to be returned. This is relative to both the database and the endpoint in questionid_number: A database specific numerical identifier
Note
ELC extended identifiers are both consumed and produced by various API routes. They consist of a three parameter, colon separated string which provides a universally unique identifier of a data resource object.
Examples of ELC IDs for the locale (/loc) route would be neot:dst:998 or pbdb:col:9191. Because of the database specific names for locale data objects, neotoma will only use dst (dataset) and PBDB will only use col (collection).
bbox=POLYGON((...))- Geographic bounding box for constraining the response. Must be a strictly formatted OGC WKT Polygon. The unaffiliated tool OpenStreetMap WKT Playground may be useful in graphically creating a polygon. Paste the generated WKT string into the
bboxfield of the ELC API. Type: str
agerange=geologic_age,[value,value][geologic_age|value]- A single named geologic age or a comma-separated pair of numerical ages, geologic ages or a combination of the two. Order does not matter, returned ages will always reflect the minimum and maximum from the pairwise set. Type: str or float
Note
If a list of ELC universal identifiers, idlist, is not provided, then either bbox or agerange must be specified.
ageunits=ybp|ka|ma- Units of geologic age to be used in the query. Age values passed to the API will be interpreted in the context of this parameter. All time specific returned values will also be converted to match this parameter. Type: str. Default: “Ma”
coordtype=modern|paleo- Configure the type of cartesian coordinates to be included in the response. Most resource databases will store the geography of occurrences and other data objects using modern day coordinates. However, with some limitations (see
misc/paleocoordinatesroute below) the API is able to convert the coordinates in to a historical projection. Type: str. Default: “modern”
limit=value- Impose a limit on the number of records returned from each database. Useful for testing or in conjuction with the
offsetparameter. Set to a very large number to negate any default limits set on any of the subqueried database resources. Type: int. Default: “999999”
offset=value- Select a sequential record number to begin the return. Useful in conjunction with
limitto chunk very large returns. For example,?limit=1000&offset=0would return the first 1000 records and?limit=1000&offset=1000the next 1000 records. Handling of this is specific to the resource database and has no relationship of any data record number, merely a database table row. If not included, the response will always begin with the first record. Type: int
output=json|csv- File format of the data return. Serialized JSON or tabular CSV. The meta-data block is a separate JSON object and thus is not included in the CSV file. The file name of the CSV file will include a shortened MD5 hash of the response data for identification purposes. Type: str. Default: “json”
show=all|poll|idxConfigure the objects to be included in the return. This parameter is ignored if the selected output format is “csv”. Type: str. Default: “all”
all: All data records and meta-datapoll: Only the meta-data block with summary statisticsidx: A list of the endpoints primary data indicies
run=all|database_name[,database_name, ...]- Single or comma separated list of resource databases for the API to query. Type: str. Default: “all”
Examples
See also
Query based on known identification numbers obtained from a different endpoint or elsewhere:
Find locales within a geographic bound roughly covering the Australian state of Victoria:
Note: The WKT format incudes spaces and the “%20”s in string above indicate these spaces (aka. an escape code). These should be automatically inserted if you paste in a WKT polygon string from a site like BoundingBox.
References¶
References returns bibliographic information on the publications from which other data are derived.
- Base path
http://earthlifeconsortium.org/api_v1/ref?
Parameters
idlist=database:datatype:id_number,[...]- Comma separated list of database specific ID numbers in the ELC extended format:
database: Subquery database name. Only first four characters are read so, for example, either “neot” or “neotoma” may be useddatatype: Short name for the data object to be returned. This is relative to both the database and the endpoint in questionid_number: A database specific numerical identifier
Note
Examples of valid ELC IDs for the references (/ref) route include pbdb:ref:100 and neot:pub:234. Database specific datatype names are again used in the ID construct, the ELC API route happens to be called /ref merely because there can only be one name.
output=json|csv|bibjson|ris- File format of the data return. Serialized JSON, structured BibJSON, tabular CSV or RIS interchange formats. The meta-data block is a separate JSON object and thus is not included in the CSV file. The file name of the CSV file will include a shortened MD5 hash of the response data for identification purposes. Type: str. Default: “bibjson”
show=all|poll|idxConfigure the objects to be included in the return. This parameter is ignored if the selected output format is “csv”. Type: str. Default: “all”
all: All data records and meta-datapoll: Only the meta-data block with summary statisticsidx: A list of the endpoints primary data indicies
run=all|database_name[,database_name, ...]- Single or comma separated list of resource databases for the API to query. Type: str. Default: “all”
Examples
See also
Specify a list of references and use the default output format of BibJSON [1]
Taxonomy¶
Taxonomy returns the classification of a given taxon.
- Base path
http://earthlifeconsortium.org/api_v1/tax?
Parameters
taxon=taxon_name|genus+species- A single name or comma-separated list of taxa at any taxonomic level or a 2-3 word pair referring to a single species. As spaces are not allowed in HTTP URLs, the taxon names must be connected by a “+” symbol or a “%20” escape sequence. Type: str.
Note
Paleobiology Database: Taxonomic names returned by the Paleobiology Database reflect synonymies as entered from the published scientific literature and are dynamically updated. Documentation of the Paleobiology Database data model is provided by Peters, S.E. and McClennen, M., 2016. The Paleobiology Database application programming interface. Paleobiology, 42(1), pp.1-7.
Neotoma: Taxonomic names returned by the Neotoma databases reflect a static taxonomy as determined by taxonomic experts. Details of these determinations can be found here.
ELC API returns for any given taxon will include each database’s understanding of what is contained in the given taxon. If the taxonomic name does NOT occur in the given database, the ELC API will not return any data from that database. These two taxonomic concepts may not be the same in each included database.
idlist=database:datatype:id_number,[...]- Comma separated list of database specific ID numbers in the ELC extended format:
database: Subquery database name. Only first four characters are read so, for example, either “neot” or “neotoma” may be useddatatype: Short name for the data object to be returned. This is relative to both the database and the endpoint in questionid_number: A database specific numerical identifier
Note
Either a taxon name or a list of ELC formatted taxonomic IDs must be provided. Examples of valid ELC IDs for the taxonomy (/tax) route include pbdb:txn:929 and neot:txn:34.
includelower=true|false- Include all species and subspecies of a named genera in the response. For PBDB the taxonomy system is used, for other databases, this flag triggers wildcard completion. This works well for species epithets but not for higher level taxa. Type: boolean. Default: “false”
output=json|csv- File format of the data return. Serialized JSON or tabular CSV. The meta-data block is a separate JSON object and thus is not included in the CSV file. The file name of the CSV file will include a shortened MD5 hash of the response data for identification purposes. Type: str. Default: “json”
show=all|poll|idxConfigure the objects to be included in the return. This parameter is ignored if the selected output format is “csv”. Type: str. Default: “all”
all: All data records and meta-datapoll: Only the meta-data block with summary statisticsidx: A list of the endpoints primary data indicies
run=all|database_name[,database_name, ...]- Single or comma separated list of resource databases for the API to query. Type: str. Default: “all”
Examples
See also
Search all subtaxa of order Carcharocles, making sure that megalodon is where it should be:
http://earthlifeconsortium.org/api_v1/tax?taxon=Carcharocles&includelower=true
Miscellaneous route¶
ELC utilities ancillary to core data retrieval are collected in the misc controller and are accessible by appending the desired route to the base path.
Paleocoordinates¶
Convert modern day cartesian coordinates into paleocoordinates using the GPlates [2] tectonics reconstruction model. Operationally this model is hosted by the Macrostrat Project [3] at the University of Wisconsin.
- Base path
http://earthlifeconsortium.org/api_v1/misc/paleocoords?
Parameters
coords=latitude,longitude- Modern day coordinates ranging from latitude -90 to 90 (southern latitudes are negative) and longitude -180 to 180 (western longitudes are negative) decimal degrees of arbitrary precision. Type: float
Warning
Due to restriction in GPlates, some coordinates are not rotatable. In this case, an error message will be returned.
age=value- Historical age of desired paleocoordinates where
valueis an integer from 1 to 580 Ma or a named geologic age. If a numerical age is specified, it may be in the units of the ageunits parameter. Type: str or int
Note
The Ma 580 limit only applies to the paleocoordinates calculation. agerange searches in other API routes refer to the actual ages of the paleobiological records and have no limits.
ageunits=ybp|ka|ma- Units of geologic age to be used in the query. Age values passed to the API will be interpreted in the context of this parameter. All time specific returned values will also be converted to match this parameter. Type: str. Default: “Ma”
Examples
See also
Determine the paleocoordinates of Washington D.C. in the middle of the Eocene:
http://earthlifeconsortium.org/api_v1/misc/paleocoords?coords=38.9,-77.02&age=eocene
Timebounds¶
Return the oldest and youngest ages (bounds) spanning the specified range. Geologic ages are resolved according to ICS definitions [4].
- Base path
http://earthlifeconsortium.org/api_v1/misc/timebound?
Parameters
agerange=geologic_age,[value,value][geologic_age|value]- A single named geologic age or a comma-separated pair of numerical ages, geologic ages or a combination of the two. Order does not matter, returned ages will always reflect the minimum and maximum from the pairwise set. Type: str or float
ageunits=ybp|ka|ma- Units of geologic age to be used in the query. Age values passed to the API will be interpreted in the context of this parameter. All time specific returned values will also be converted to match this parameter. Type: str. Default: “Ma”
Examples
See also
Determine the earliest and latest age from the Late Cretaceous epoch through the Selandian stage of the Paleocene:
http://earthlifeconsortium.org/api_v1/misc/timebound?agerange=late+cretaceous,selandian
Time bound of just the Triassic in units of years before present:
http://earthlifeconsortium.org/api_v1/misc/timebound?agerange=triassic&ageunits=ybp
Time range of the Miocene through a selected age of 2 Ma:
http://earthlifeconsortium.org/api_v1/misc/timebound?agerange=2,miocene
Subtaxa¶
Return a list of all taxonomic names hierarchically below the specified taxon, optionally including synonyms.
Warning
This tool leverages the Paleobiology Database taxonomy system and, while comprehensive for many classes, may lack taxa for species that are not the historical focus of the database.
- Base path
http://earthlifeconsortium.org/api_v1/misc/subtaxa?
Parameters
taxon=taxon_name|genus+species- A single name or comma-separated list of taxa at any taxonomic level or a 2-3 word pair referring to a single species. As spaces are not allowed in HTTP URLs, the taxon names must be connected by a “+” symbol or a “%20” escape sequence. Type: str.
synonyms=true|false- Include known synonymous names for the children of the specified parent taxon together with recognized names. If “False” only the primary sub taxa will be retrieved. Type: Boolean. Default: “true”
Examples
See also
Retrieve all lower taxa of the family Tyrannosauridae excluding synonyms:
http://earthlifeconsortium.org/api_v1/misc/subtaxa?taxon=tyrannosauridae&synonyms=false
Check to see if there are any known synonyms of Dorudon atrox:
http://earthlifeconsortium.org/api_v1/misc/subtaxa?taxon=dorudon+atrox&synonyms=true
Mobile¶
A custom route designed to return a combination of occurrence data with associated taxonomic and select environmental details. The response is nested JSON with a highly compact vocabulary.
- Base path
http://earthlifeconsortium.org/api_v1/misc/mobile?
Parameters
taxon=taxon_name|genus+species- A single name or comma-separated list of taxa at any taxonomic level or a 2-3 word pair referring to a single species. As spaces are not allowed in HTTP URLs, the taxon names must be connected by a “+” symbol or a “%20” escape sequence. Type: str.
bbox=POLYGON((...))- Geographic bounding box for constraining the response. Must be a strictly formatted OGC WKT Polygon. The unaffiliated tool OpenStreetMap WKT Playground may be useful in graphically creating a polygon. Paste the generated WKT string into the
bboxfield of the ELC API. Type: str
Compact vocabulary
| src | ELC formatted unique occurrence ID |
| loc | Location parameter block |
|---|---|
| age | Early, Late age (Ma) |
| crd | Coordinates (GeoJSON) |
| pla | Place (county/district, state/province, country) |
| ste | Site/Collection description |
| org | Organism parameter block |
|---|---|
| img | Phylopic image URI |
| itv | Early, Late geologic existence interval |
| nam | Common name |
| sts | Status of modern existence |
| txn | Taxonomic name |
| eco | Ecology parameter block |
|---|---|
| dte | Diet/Feeding mode |
| env | Environmental description |
| grp | Ecological/Taxonomic grouping/env basis |
| hab | Life habitat, grouping or depth |
| mot | Motility and/or attachment |
| ont | Ontology |
| rep | Mode of reproduction |
| typ | Collection/Dataset type |
| vis | Vision capability |
Examples
See also
Find all occurrences of the extant plant Borreria and the rodent Dasyprocta in Brazil:
- Metadata
- All
fullorpollJSON responses include a metadata block which importantly indicates the URLs composed for the resource databases in addition to a timestamp, the age units and the type of geographic coordinates retrieved. If desired, the subquery URL may be used to delve deeper into each individual database. - Error handling
- API errors are reported according to IETF [5] standards including both server level 500 series and client level 400 series HTTP errors. As the ELC API leverages remote data service resources for much of it’s functionality, bad requests to or lack of availability of these remote services may result in the propogation of a 400 level error as ELC is the client in this circumstance.
Footnotes
| [1] | BibJSON: Representing bibliographic metadata in JSON. http://okfnlabs.org/bibjson/ |
| [2] | Wright, N., S. Zahirovic, R. D. Müller, and M. Seton (2013), Towards community-driven, open-access paleogeographic reconstructions: integrating open-access paleogeographic and paleobiology data with plate tectonics, Biogeosciences, 10, 1529-1541. DOI: 10.5194/bg-10-1529-2013 |
| [3] | Macrostrat public API. https://macrostrat.org/#api |
| [4] | Gradstein, F. M., J. G. Ogg, M. D. Schmitz, and G. M. Ogg. 2012. A Geologic Time Scale 2012, Volume 2. Elsevier, Amsterdam, 1144 pp. |
| [5] | Internet Engineering Task Force: Problem Details for HTTP APIs. https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00 |
