Description
Returns location-based look-up data based on the rtype (Region Type) parameter; rtype options are: bcr, country, subnational1, and subnational2. Non-parameterized list URIs - list all records for a specific rtype, list plus sub-category parameter URIs - list those records matching the sub-category parameter, find URIs - search for matching records in the primary name field on whole word or partial word stubs passed visa the match parameter. The default result format is CSV.
This is part of the eBird version 1.1 API.
URL
Base URL
http://ebird.org/ws1.1/ref/location
Examples
Minimal list:
http://ebird.org/ws1.1/ref/location/list?rtype=bcr
http://ebird.org/ws1.1/ref/location/list?rtype=country
http://ebird.org/ws1.1/ref/location/list?rtype=subnational1
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2
Minimal find:
http://ebird.org/ws1.1/ref/location/find?rtype=bcr&match=north
http://ebird.org/ws1.1/ref/location/find?rtype=country&match=stan
http://ebird.org/ws1.1/ref/location/find?rtype=subnational1&match=new
http://ebird.org/ws1.1/ref/location/find?rtype=subnational2&match=west
Fully specified list:
http://ebird.org/ws1.1/ref/location/list?rtype=bcr&fmt=csv
http://ebird.org/ws1.1/ref/location/list?rtype=bcr&fmt=xml
http://ebird.org/ws1.1/ref/location/list?rtype=country&fmt=csv
http://ebird.org/ws1.1/ref/location/list?rtype=country&fmt=xml
http://ebird.org/ws1.1/ref/location/list?rtype=subnational1&fmt=csv
http://ebird.org/ws1.1/ref/location/list?rtype=subnational1&fmt=xml
http://ebird.org/ws1.1/ref/location/list?rtype=subnational1&countryCode=AD
http://ebird.org/ws1.1/ref/location/list?rtype=subnational1&countryCode=JP&fmt=csv
http://ebird.org/ws1.1/ref/location/list?rtype=subnational1&countryCode=ZW&fmt=xml
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2&fmt=csv
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2&fmt=xml
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2&countryCode=US
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2&countryCode=CA&fmt=csv
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2&countryCode=NZ&fmt=xml
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2&subnational1Code=GB-ENG
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2&subnational1Code=CA-AB&fmt=csv
http://ebird.org/ws1.1/ref/location/list?rtype=subnational2&subnational1Code=nz-can&fmt=xml
Fully specified find:
http://ebird.org/ws1.1/ref/location/find?rtype=bcr&match=south&fmt=csv
http://ebird.org/ws1.1/ref/location/find?rtype=bcr&match=west&fmt=xml
http://ebird.org/ws1.1/ref/location/find?rtype=country&match=united&fmt=csv
http://ebird.org/ws1.1/ref/location/find?rtype=country&match=republic&fmt=xml
http://ebird.org/ws1.1/ref/location/find?rtype=subnational1&match=west&fmt=csv
http://ebird.org/ws1.1/ref/location/find?rtype=subnational1&match=south&fmt=xml
http://ebird.org/ws1.1/ref/location/find?rtype=subnational2&match=west&fmt=csv
http://ebird.org/ws1.1/ref/location/find?rtype=subnational2&match=south&fmt=xml
Parameter Descriptions
Parameter Name |
Required |
Default |
Value Options |
Example Value |
Description |
---|---|---|---|---|---|
fmt |
no |
csv |
xml,csv |
xml |
format of the response |
countryCode |
no |
none |
Any valid country-code, see http://ebird.org/ws1.1/ref/location/list?rtype=country&fmt=xml. |
NZ |
list request parameter valid for rtype=subnational1* and *rtype=subnational2 |
subnational1Code |
no |
none |
Any valid subnationa1-code, see http://ebird.org/ws1.1/ref/location/list?rtype=subnational1&fmt=xml. |
NZ-MWT |
list request parameter valid for rtype=subnational2 |
Result Fields
Field (XML) |
Description |
---|---|
sci-name |
Scientific name |
com-name |
Common name |
taxon-id |
Taxonomic Concept identifier, note this is currently in test |
Example Responses
CSV
Rhea americana,Greater Rhea,TC000004 Rhea pennata,Lesser Rhea, TC000005
XML
<response> <header> <locale country="" language="en"/> <timestamp> 2009-07-08T10:39:42.150-04:00 </timestamp> <criteria> <locale country="" language="en"/> <cat> species </cat> <fmt> xml </fmt> </criteria> </header> <result> <taxa> <com-name> Greater Rhea </com-name> <sci-name> Rhea americana </sci-name> <taxon-id> TC00000004 </taxon-id> </taxa> <taxa> <com-name> Lesser Rhea </com-name> <sci-name> Rhea pennata </sci-name> <taxon-id> TC00000005 </taxon-id> </taxa> </response>
Caching Information
For details on caching of results by our servers, see eBird-1.1-CacheInformation