Description
Returns a list of all species in the eBird taxonomy for the given combination of categories. The default category is "species". Any taxon with the category of 'species' may be used as a parameter in service calls that take a scientific name. Any taxon not in this category will be rejected by these services at this time.
This is part of the eBird version 1.1 API.
URL
Base URL
http://ebird.org/ws1.1/ref/taxa
Examples
Minimal:
http://ebird.org/ws1.1/ref/taxa/ebird
Fully specified:
http://ebird.org/ws1.1/ref/taxa/ebird?cat=species&fmt=xml&locale=en_US
http://ebird.org/ws1.1/ref/taxa/ebird?cat=species,hybrid&fmt=json&locale=en_US
Parameter Descriptions
Parameter Name | Required | Default | Value Options | Example Value | Description |
|---|---|---|---|---|---|
cat | no | species | domestic,form,hybrid,intergrade,issf,slash,species,spuh | hybrid | These can be comma-separated to include multiple categories in the results. For more info about the meaning of species categories, see http://ebird.org/content/ebird/about/ebird-taxonomy. |
locale | no | en_US | en,en_US,de,en_AE,en_AU,en_IN,en_NZ,en_UK,en_ZA,es,es_AR,es_CL,es_CU es_DO,es_ES,es_MX,es_PA,es_PR,fi,fr,fr_HT,ht_HT,in,is,pt_BR,pt_PT,tr,zh | fr_CA | The locale for the taxon common name |
fmt | no | csv | xml,json,csv | xml |
|
Resources
The human readable version of the current eBird taxonomy can also be downloaded here.
Result Fields
Field (XML) | Description |
|---|---|
sci-name | Scientific name |
com-name | Common name |
taxon-id | Taxonomic Concept identifier, note this is currently in test |
| species-code | An internal code for the taxon |
| category | The taxonomic category (species, slash, etc.) |
| taxon-order | A float representing the taxonomic order |
| com-name-codes | Space-delimited quick find codes for English primary common name |
| sci-name-codes | Space-delimited quick find codes for scientific name |
| banding-codes | Official USGS banding code |
Example Responses
CSV
| SCIENTIFIC_NAME | COMMON_NAME | TAXON_ID | SPECIES_CODE | CATEGORY | TAXON_ORDER | COM_NAME_CODES | SCI_NAME_CODES | BANDING_CODES | |
| Struthio camelus | Ostrich | TC000001 | ostric1 | species | 1 | SOOS OSTR COOS | STCA | ||
XML
<?xml version="1.0" encoding="UTF-8"?>
<response><header><locale country="US" language="en"/><timestamp>2015-04-10T10:23:47.513-04:00</timestamp><criteria find-command-flag="false"><fmt>xml</fmt><dataset>eBird</dataset><version>1.55</version><cat>species</cat><locale country="US" language="en"/></criteria></header>
<result>
<taxa><taxon-id>TC000001</taxon-id><sci-name-codes>STCA</sci-name-codes><taxon-order>1.0</taxon-order><category>species</category><species-code>ostric1</species-code><com-name-codes>SOOS</com-name-codes><com-name-codes>OSTR</com-name-codes><com-name-codes>COOS</com-name-codes><com-name>Ostrich</com-name><sci-name>Struthio camelus</sci-name></taxa><taxa><taxon-id>TC000004</taxon-id><sci-name-codes>RHAM</sci-name-codes><taxon-order>7.0</taxon-order><category>species</category><species-code>grerhe1</species-code><com-name-codes>GRRH</com-name-codes><com-name>Greater Rhea</com-name><sci-name>Rhea americana</sci-name></taxa>
<taxa><taxon-id>TC000005</taxon-id><sci-name-codes>RHPE</sci-name-codes><taxon-order>13.0</taxon-order><category>species</category><species-code>lesrhe2</species-code><com-name-codes>LERH</com-name-codes><com-name>Lesser Rhea</com-name><sci-name>Rhea pennata</sci-name></taxa><taxa><taxon-id>TC000018</taxon-id><sci-name-codes>NOJU</sci-name-codes><taxon-order>32.0</taxon-order><category>species</category><species-code>tabtin1</species-code><com-name-codes>TBTI</com-name-codes><com-name>Tawny-breasted Tinamou</com-name><sci-name>Nothocercus julius</sci-name></taxa>
</result>
JSON
[{"bandingCodes":[],"category":"species","comName":"Ostrich","comNameCodes":["SOOS","OSTR","COOS"],"sciName":"Struthio camelus","sciNameCodes":["STCA"],"speciesCode":"ostric1","taxonID":"TC000001","taxonOrder":1},{"bandingCodes":[],"category":"species","comName":"Greater Rhea","comNameCodes":["GRRH"],"sciName":"Rhea americana","sciNameCodes":["RHAM"],"speciesCode":"grerhe1","taxonID":"TC000004","taxonOrder":7},{"bandingCodes":[],"category":"species","comName":"Lesser Rhea","comNameCodes":["LERH"],"sciName":"Rhea pennata","sciNameCodes":["RHPE"],"speciesCode":"lesrhe2","taxonID":"TC000005","taxonOrder":13}]Caching Information
For details on caching of results by our servers, see eBird-1.1-CacheInformation
10 Comments
Anonymous
json format is also supported but its details are not included
Anonymous
We're adding a taxon-id to this API. This ID will represent a stable identifier for the bird populations and will not change even when the common and/or scientific names may change depending on taxonomic revisions.
Anonymous
When I click on your sample link (with locale=en_US) I get the full eBird world taxonomy not just the US list. The locale specification seems to have no effect. Also, fmt=csv returns an empty response when the locale is anything other than en_US. I want en_CO (the english list for the country of Colombia). What am I doing wrong? Peter Bono (pbono@prba.com)
user-ad27b
The locale parameter will only affect the language of the common names returned; it won't filter the taxonomy by location.
Anonymous
Just to be clear that I understand you: this API ALWAYS returns the ENTIRE eBird list of species (as controlled by the species category parameter). It then CHANGES the COMMON NAME of ONLY THOSE SPECIES that occur within the geographic range of the country in the locale specifier, rendering the name in the language portion of the locale specifier. For example, if I specify locale=es_PA, then Lesser Rhea is not return in Spanish because the Lesser Rhea does not occur in Panama, whereas if I specify locale=es_CL, then the common name for Rhea pennata will be returned with its (Chilean) Spanish name.
Do you have in the works any API webservices that will filter by the country/political division (e.g., US-MA (Massachusetts) or EC (Ecuador))?
Thanks, Peter
Anonymous
Peter,
That's more or less correct, if we have the common name in the language requested, we return those. Let's say you request a locale of es_PA, if we have a Panamanian common name for a species, that will get returned. If we don't have Panamanian Spanish, but we do have Spanish, we'll return the generic Spanish name. If we don't have either, it falls back to English. There isn't actually any checks we do on our side to determine if the bird occurs in Panama, only whether we happen to have a Panamanian name for it.
The closest we have in the works is a checklist API which will return species and count limits for a specific checklist. However, these checklists might be applicable to a country, state or even a county so there isn't anything which will give you all the species in the US.
Jeff
Anonymous
What about band codes? Could that get included in this API?
Anonymous
We don't have any plans to add banding codes to the API though it's something we'll consider for the next release. Thanks for the suggestion.
Anonymous
Can you provide more information for each bird?
Order, Family (common and scientific), shorthand names (as used in your eBird map URLs -- so it can be linked to directly).
Anonymous
Including Family & Order information would be a huge help, since they are commonly used to group species together.