Web Services
Example Links
The links in the navigation menu provide a set of
example links for each vocabulary to help you construct your calls to the web
services for the vocabularies hosted on this site. If you learn best by example
this is probably the best option. Alternatively read on below for more detailed information
on how to construct your queries.
How the Links are Constructed
This site provides a number of web services based around the vocabularies that it is used to maintain. These services are RESTful XML based services which we will try to enhance and add to as demand increases. Possible enhancements that we're thinking about include making the services available as JSON and defining an API to allow other sites to submit alternative terms for the concepts lodged on this site.
We have a service which lists the vocabularies being managed through this site and being managed by it:
http://vocabularies.gbif.org/services/gbif/vocabularies/
You may notice this is a short list - we are working on moving a number of other taxonomically focussed vocabularies into the site to really make it useful - for the full list see http://gnapartnership.org/gbif-scratchpads/ticket/82
For each of the vocabularies you can now:
- Retrieve all concepts and terms in a vocabulary eg http://vocabularies.gbif.org/services/gbif/country/
- Retrieve a single concept including alternative terms eg http://vocabularies.gbif.org/services/gbif/country/BO&alternatives=1
- Search for concept by name eg http://vocabularies.gbif.org/services/gbif/country/name=arab
- Retrieve terms matching a specific language or list of languages for a concept eg http://vocabularies.gbif.org/services/gbif/country/DK?lang=en,fr,af,zu,es
The best way to illustrate the services is to break the request url up so take the following stylised URL:
http://vocabularies.gbif.org/services/gbif/[vocabularyName]/{name=ABC}{identifier (all)}{?}{&alternatives=1(0)}{&lang=XX[,YY,ZZZ](all)}{&filters[filterName]=filterValue}{&limit=numberOfRecords(500)}{&page=pageNumber(0)
| Component | Definition |
|---|---|
| http://vocabularies.gbif.org | Site URL |
| services/gbif/ | Get to the web services |
| vocabularyName | The desired vocabulary you want to query - (eg 'country') |
| identifier | The standard identifier you want to retrieve from the vocabulary (eg 'BO'). If no identifier is given then all concepts for that vocabulary are returned. (Cannot be used in combination with 'name'.) |
| name | A word of 2 or more characters that you want to match terms with (eg 'arab'). Returns all concepts matching a name. (Cannot be used in combination with 'identifier'.) |
| alternatives | If set to 'true' or any non zero value (eg 'alternatives=1') then the request will return alternative terms for the concept as well as preferred terms. Defaults to 0 (false). Does not work with the 'name' argument. |
| lang | Standard ISO identifier for the language as defined by IETF RFC 4646 (http://www.ietf.org/rfc/rfc4646.txt) or successor. This is normally the ISO 639-1 two letter code for the language, or if your language is not covered by that standard the ISO 639-2/639-3 code for that language. (eg 'fr') |
| filters[filtername] | You can specify an array of filters with which to limit your query. Not all datatypes have these filters built in, but the language one does, with the most notable filter being the '639_level' filter which filters languages by the level at which they enter the ISO 639 standard for encoding languages. In this case the level can take the integer values 1, 2 or 3. |
| limit | limit the number of records returned in your query (defaults to 500) |
| page | specify the page number to return for your query (defaults to 0) |
| [] | required argument |
| {} | optional argument |
| () | the default value for optional arguments if the optional argument is not given |