The checklist bank API consists of several services with their own endpoint given underneath each service below. All services take parameters as querystring encoded GET key=value parameters and respond with an application/json content type (to view raw services we recommend the viewJSON firefox plugin, Safari will download all responses).

Global parameters and response formats

This section describes all parameters used by the API. Not all parameters are used by all services, but if they are their definition is consistent across the entire API. Please see the list of supported parameters for each individual service further down.

The JSON response objects are still subject to change. Please see this java class for the latest and greatest until we document a stable response format here.

Every JSON response (with the excetption of the navigation service) is wrapped in a simple envelope to transport error messages, counts, execution time in milli seconds and more generic information. The wrapper looks like this (with some attributes being optional and context dependent):

{
  "success": true/false,
  "error": "A short error message",
  "totalHits": 432,
  "data": {...}/[...]
}
	   

For errors or not existing identifiers matching http error codes are returned. A http 404 for objects not found, a 201 for newly created image URLs, a 400 for invalid requests with wrong parameter (values) and a 401 for unauthorised access in case of access controlled services.

callback

An optional callbackhandler for crossdomain JSONP ajax calls. The results will be returned as a javascript function instead.

page

page requested when paging. Defaults to 1 for the first page.

pagesize

pagesize, the number of records per page. Defaults to 10 in case of searches or 100 when navigating the taxonomy. The maximum allowed is 1000.

Checklist Service

http://ecat-dev.gbif.org/ws/checklist/{rkey}

The checklist service does not accept any of the shared parameters apart from callback and has only 1 optional parameter.

rkey

checklist resource key (UUID) or datasetID (integer). If null, list all available resources

type

The checklist type(s) to limit the request to. Defaults to "unti". Please use the first letters for unknown any arbitrary list of species, nomenclator name authority, taxonomic taxonomic authority, inventory not authoritative for names or taxonomy, but complete regarding metadata scope, occurrences derived from occurrence records: u n t i o

Name URI Resolver

http://ecat-dev.gbif.org/ws/resolve/

The name resolver uses the name itself as the identifier to usages. The name is encoded as a "pretty", restful URL and the service will do a fullname match against all know lexical variants of the name. It therefore always includes the canonical name alone. Note that the matching requires a full string match and does not search partially matching names! Name strings should be URL encoded if they contain non ASCII characters. Spaces can be encoded either as %20, underscore(_) or a plus symbol(+).

When only specifying the name alone, e.g http://ecat-dev.gbif.org/ws/resolve/Festuca anatolica, only GBIF Nub usages will be returned. The resolver can be told to use another checklist by appending the checklistID to the URL, e.g. http://ecat-dev.gbif.org/ws/resolve/Festuca anatolica/1001. The available checklist resources can be discovered via the checklist service.

Name Usage Service

http://ecat-dev.gbif.org/ws/usage/{id}

The name usage service supports paging.

id

usageID to retrieve name usage details. If given, all other parameters are ignored. Looking up a single usage by its id changes the behaviour of the ranks parameter. All mayor ranks if exist are always shown, but the full classification with all higher taxa including non mayor ranks like subfamily is also retrieved when ranks=x. This is a slightly costly operation so expect it to be slower. Id parameter can be provided as path argument at the end of the URL.

nid

nameID to retrieve all usages with the exact given name string. If given, takes precedence over query string searches and lexical searches and the only allowed other filter is status.

nubid

Usage id from the GBIF Backbone Taxonomy to retrieve all usages that are tied to the same nub usage. If given, takes precedence over query string searches and the only allowed other filter is status.

q

optional scientific name querystring

searchType

The scientific name search type. One of fullname canonical defaults to fullname which does a prefix seach on the full scientific name including authorship and rank marker. The canonical search does an exact, case sensitive match on the canonical name excluding authorshi or a rank marker like var.

count

if true adds totalHits to the outer wrapper listing the total number of records hit by the query. Slows down queries with many hits, so defaults to false

rkey

optional checklist resourceKey (UUID) or datasetID (integer) to limit search to a specific checklist only. To limit a request to the NUB use rkey=1. Defaults to NULL, i.e. all checklists!

type

The checklist type(s) to limit the request to. Defaults to "unti", i.e. all checklists but occurrence derived ones. Please use the first letters for unknown any arbitrary list of species, nomenclator name authority, taxonomic taxonomic authority, inventory not authoritative for names or taxonomy, but complete regarding metadata scope, occurrences derived from occurrence records: u n t i o

status

Restricts a search to usages with a taxonomic status of either accepted synonym. If not given, which is the default, searches will include both synonyms and accepted. Synonyms in this context are all non accepted usages such as hetero- or homotypical & pro parte synonyms, misapplied names or any other non accepted usage.

rank

optional rank filter to search usages of the given rank only. Please use the first letter of any one of the following list of rank abbreviations k p c o f sf g sg s is for kingdom, phylum, class, order, family, subfamily, genus, subgenus, species or infraspecific respectively.

showRanks

The list of higher darwin core ranks to show for each result. Defaults to none. If at least one rank is given counts of included taxa for all darwin core ranks are added. Please use the first letters for kingdom, phylum, class, order, family, genus, subgenus: k p c o f g s with also correspond to the count element name, i.e. numF for number of families, numG number of genera, numS number of species and numIS for number of infraspecific taxa. For example kcfg to list kingdom, class, family and genus for each result. If a requested rank is not available because it is unknown or the record represents a higher rank, the corresponding json element will be existing, but empty. You will get a better performance the less ranks you inlcude, so be nice and don't ask for more than you need.

showImages

If true or 1 will add an imageURL and thumbURL for each record. We try our best to keep thumbnail urls in addition to the original url, but a thumbURL might not be available for all images. Example: showImages=true

showVernaculars

Optionally includes vernacular names for each record. The parameter accepts a list of iso2 language codes, seperated by pipes |. for example showVernaculars=en|de|es to add English, German and Spanish vernacular names. To get all available names in all languages specify showVernaculars=all.

showIds

If true or 1 will include all known alternative identifier and links, e.g. the original identifier used by the source for each record. Note that some records might not have any alternative ids at all. Defaults to false.

sort

The sort order of returned results. none: no order (very fast, ideal for autocomplete, but no stable order for paging), alpha: alphabetical order, rank: ordered by rank and alphabetically within each rank, tax: taxonomical "depth first" order with children of a taxon following immediately its parent - ideal for nested output. Defaults to none

Navigation Service

http://ecat-dev.gbif.org/ws/nav/{id}

The navigation service supports paging, but currently is not wrapped into the standard envelope but exposes the data directly!

id

usageID to retrieve list of children. Defaults to nothing so that root taxa/usages are returned. Id parameter can be provided as path argument at the end of the URL.

rkey

optional checklist checklist resource key (UUID) or datasetID (integer) to retrieve root usages in case no id has been given. Defaults to NUB checklist rkey=1

rank

optional rank filter to search usages of the given rank only. Please use the first letter of any one of the following list of rank abbreviations k p c o f sf g sg s is for kingdom, phylum, class, order, family, subfamily, genus, subgenus, species or infraspecific respectively.

showRanks

The list of higher darwin core ranks to show for each result. Defaults to none. If at least one rank is given counts of included taxa for all darwin core ranks are added. Please use the first letters for kingdom, phylum, class, order, family, genus, subgenus: k p c o f g s with also correspond to the count element name, i.e. numF for number of families, numG number of genera, numS number of species and numIS for number of infraspecific taxa. For example kcfg to list kingdom, class, family and genus for each result. If a requested rank is not available because it is unknown or the record represents a higher rank, the corresponding json element will be existing, but empty. You will get a better performance the less ranks you inlcude, so be nice and don't ask for more than you need.

showImages

If true or 1 will add an imageURL and thumbURL for each record. We try our best to keep thumbnail urls in addition to the original url, but a thumbURL might not be available for all images. Example: showImages=true

showVernaculars

Optionally includes vernacular names for each record. The parameter accepts a list of iso2 language codes, seperated by pipes |. for example showVernaculars=en|de|es to add English, German and Spanish vernacular names. To get all available names in all languages specify showVernaculars=all.

showIds

If true or 1 will include all known alternative identifier and links, e.g. the original identifier used by the source for each record. Note that some records might not have any alternative ids at all. Defaults to false.

sort

The sort order of returned results. none: no order (very fast, ideal for autocomplete, but no stable order for paging), alpha: alphabetical order, rank: ordered by rank and alphabetically within each rank, tax: taxonomical "depth first" order with children of a taxon following immediately its parent - ideal for nested output. Defaults to none

Name String Service

http://ecat-dev.gbif.org/ws/name/{nid}

The name string service supports paging. The results are ordered in a stable sequence for paging, but not alphabetically as you would expect! We are working on fixing that

nid

nameID to retrieve name details for. If given, all other parameters below are ignored. NameId parameter can be provided as path argument at the end of the URL.

q

optional scientific name querystring

count

if true adds totalHits to the outer wrapper listing the total number of records hit by the query. Slows down queries with many hits, so defaults to false

text

if true returns results as pipe delimited text with fixed pagesize=10. This simple format is commonly used for autocompletes, e.g. by jQuery. Defaults to false

lexical

if true shows lexical groups that have at least one matching name. Defaults to false

status

Restrict a search to names with a management status of either blacklisted doubtful wellformed. If not given, which is the default, searches will include all names but the blacklisted ones

Image Service

http://ecat-dev.gbif.org/ws/image/{id}

The image service does not accept any of the global parameters apart from callback and has only 1 required parameter:

id

usageID to retrieve list of images for. Id parameter can be provided as path argument at the end of the URL.

url

URL string to add as the preferred image to the given usage. If already existing the URL will be promoted as the default image, but not added a second time.

http://ecat-dev.gbif.org/ws/checklist/

Available non occurrence derived checklists

http://ecat-dev.gbif.org/ws/nav/

Nub root taxa

http://ecat-dev.gbif.org/ws/usage/?q=Blechnum&rkey=1&sort=alpha&pagesize=100

Search for "Blechnum spicant" in the Nub checklist and return 100 hits sorted alphabetically

http://ecat-dev.gbif.org/ws/usage/1

Usages details of "Animalia" in the Nub

http://ecat-dev.gbif.org/ws/nav/?id=13729267&pagesize=5"

First 5 Children of "Blechnum spicant"