Classic APIs

The APIs for names, hierarchies, collections, text and media originate in EOL v2 and will be rebuilt with back compatibility over the course of 2019. The following services are supported:

Ping

This method will either fail (in which case the EOL error page will most likely be returned) or return a message of Success. There are no other possible messages.

Parameters: none

Search

The XML search response implements the OpenSearch response format using Atom 1.0. See http://www.opensearch.org/Specifications/OpenSearch/1.1 for the full OpenSearch specification

Given the vast number of scientific and common names (nearly 20 million in total) it is a difficult task to provide a user with exactly the species they are hoping to find. For example there are several bird species of named Robin (American Robin, Alpine Robin, Smoky Robin), and several fish species named Robin, and a taxonomist named Robin who has named dozens of species. We have included an 'exact' parameter to return only results whose name matches the search term in its entirety, but we cannot guarantee the returned taxa are taxa you intended to find.

sample: https://eol.org/api/search/1.0.json?q=Pinus%2Bcontorta&page=1&key=

Parameters:

Name Values Default Notes
q any string the query string
page any integer 1 a maximum of 30 results are returned per page. This parameter allows you to fetch more pages of results if there are more than 30 matches
exact true, false false will find taxon pages if the title or any synonym or common name exactly matches the search term
filter_by_taxon_concept_id any integer given an EOL page ID, search results will be limited to members of that taxonomic group
filter_by_hierarchy_entry_id any integer given a Hierarchy Entry ID, search results will be limited to members of that taxonomic group
filter_by_string any string given a search term, an exact search will be made and that matching page will be used as the taxonomic group against which to filter search results
cache_ttl any integer the number of seconds you wish to have the response cached

Collections

Given the identifier for a collection this API will return all metadata about the collection and the items it contains. The item list can be filtered by item type, and sorted on the listed attributes. Some items will contain an optional 'sort_field' attribute. The sort field is a user-supplied string that is a special annotation on a collection item. It may be any character string, but if it is a date, it should conform to the format YYYY-MM-DD.

Parameters:

Name Values Default Notes
id any integer
page any integer 1
per_page 0-500 50
filter articles, collections, communities, images, sounds, taxa, users, video
sort_by recently_added, oldest, alphabetical, reverse_alphabetical, richness, rating, sort_field, reverse_sort_field recently_added
sort_field any string If a sort_field parameter is included, only collection items whose sort field exactly matches the given string will be returned
cache_ttl any integer the number of seconds you wish to have the response cached
language ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv, tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko en provides the results in the specified language

Pages

This method takes an EOL page identifier and returns the scientific name for that page, and optionally returns information about common names, media (text, images and videos), and references to the hierarchies which recognize the taxon described on the page.

The Darwin Core Taxon elements (dwct:Taxon) under 'additionalInformation' include identifiers for nodes in hierarchies which EOL indexes. They contain a dc:identifier which is the unique ID for the taxon in the provider's database. For example for the Taxon element for a node in the ITIS hierarchy, the dc:identifier will be the ITIS TSN. The dwct:taxonID element contains the EOL identifier to be used in the hierarchy_entries API. There is no singular EOL taxonomic hierarchy, rather EOL indexes many hierarchies and compares them to figure out which nodes are referring to the same taxa. These taxon elements represent these hierarchy nodes, which is why there are potentially several of them for a given EOL page. Refer to the documentation on the hierarchy_entries API for more information.

If the 'details' parameter is not set then only the data object identifier, data type, and, in the case of articles, subject will be returned. The data type will be a value from the Dublin Core resource type vocabulary. The text subject will be one of the EOL accepted subjects.

If multiple media objects are returned, the list will be ordered by object type. Within each type, items are sorted by vetted status ('Trusted' > 'Unreviewed' > 'Untrusted'), and then by data rating. However, within certain data types, specific items are given the highest priority: if one of these items is returned, it will be listed first. For images, exemplar images have highest priority. With text types, the overview text has highest priority.

sample: https://eol.org/api/pages/1.0/491995.json?details=true&images_per_page=10

Parameters:

Name Values Default Notes
batch true, false false returns either a batch or not
id any string
images_per_page 0-75 limits the number of returned objects
images_page any integer 1 images page
videos_per_page 0-75 limits the number of returned objects
videos_page any integer 1 videos page
sounds_per_page 0-75 limits the number of returned objects
sounds_page any integer 1 sounds page
maps_per_page 0-75 limits the number of returned objects
maps_page any integer 1 maps page
texts_per_page 0-75 limits the number of returned objects
texts_page any integer 1 texts page
subjects see notes overview 'overview' to return the overview text (if exists), a pipe | delimited list of subject names from the list of EOL accepted subjects (e.g. TaxonBiology, FossilHistory), or 'all' to get text in any subject. Always returns an overview text as a first result (if one exists in the given context).
licenses cc-by, cc-by-nc, cc-by-sa, cc-by-nc-sa, pd [public domain], na [not applicable], all all a pipe | delimited list of licenses or 'all' to get objects under any license. Licenses abbreviated cc- are all Creative Commons licenses. Visit their site for more information on the various licenses they offer.
details true, false false include all metadata for data objects
common_names true, false false return all common names for the page's taxon
synonyms true, false false return all synonyms for the page's taxon
references true, false false return all references for the page's taxon
taxonomy true, false false return any taxonomy details from different taxon hierarchy providers, in an array named "taxonConcepts"
vetted 0,1,2,3,4 0 If 'vetted' is given a value of '1', then only trusted content will be returned. If 'vetted' is '2', then only trusted and unreviewed content will be returned (untrusted content will not be returned). If 'vetted' is '3', then only unreviewed content will be returned. If 'vetted' is '4', then only untrusted content will be returned.The default is to return all content.
cache_ttl any integer the number of seconds you wish to have the response cached
language ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv, tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko en provides the results in the specified language

Data Objects

Given the identifier for a data object this API will return all metadata about the object as submitted to EOL by the contributing content partner. The content partner is cited in the first agent element and has the role of 'partner'.

Image objects will contain two 'mediaURL' elements - the first being the URL of the image on the provider's website, and the second is the URL of the cached version of the media hosted on an EOL server. The EOL version of the image will have been resized (preserving the aspect ratio) if the original image is larger than 460 pixels wide or 345 pixels in height.

**Note change from EOL v2**: Text objects are now treated differently from other media in the database. You must now call data_objects_articles instead of data_objects, if using DataObject version IDs. 16 character GUIDs for text objects can still use the data_objects service. Parameters remain the same either way.

Parameters:

Name Values Default Notes
id any string the ID parameter can either be an integer (a DataObject version ID) or a 16 character GUID which will return the latest version of that object
taxonomy true, false true return any taxonomy details from different taxon hierarchy providers, in an array named "taxonConcepts"
language ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv, tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko en provides the results in the specified language.
cache_ttl any integer the number of seconds you wish to have the response cached