{toc}
h2. 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 via the *match* parameter. The default result format is CSV.
This is part of the [eBird version 1.1 API|eBird API 1.1].
h2. 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]
h2. 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]. \\ | CA \\ | *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* \\ |
h2. BCR Result Fields
|| *Field (XML)* || *Description* ||
| primary-name | BCR Primary nameName |
| region-code | BCR codeCode |
h3. Example Responses
h4. CSV
{noformat}
West Gulf Coastal Plain/Ouachitas,25
Southeastern Coastal Plain,27
New England/Mid-atlantic Coast,30
Coastal California,32
Gulf Coastal Prairie,37
{noformat}
h4. XML
{noformat}
<response>
<header>
<locale country="" language="en"/>
<timestamp>2014-04-03T11:37:01.761-04:00</timestamp>
<criteria find-command-flag="true">
<fmt>xml</fmt>
<match>coast</match>
<region-type>bcr</region-type>
<rtype>bcr</rtype>
</criteria>
</header>
<result>
<location>
<primary-name>West Gulf Coastal Plain/Ouachitas</primary-name>
<region-code>25</region-code>
</location>
<location>
<primary-name>Southeastern Coastal Plain</primary-name>
<region-code>27</region-code>
</location>
<location>
<primary-name>New England/Mid-atlantic Coast</primary-name>
<region-code>30</region-code>
</location>
<location>
<primary-name>Coastal California</primary-name>
<region-code>32</region-code>
</location>
<location>
<primary-name>Gulf Coastal Prairie</primary-name>
<region-code>37</region-code>
</location>
</result>
</response>
{noformat}
h2. Country Result Fields
|| *Field (XML)* || *Description* ||
| scicountry-namecode | ScientificCountry nameCode |
| com-name | CommonCountry nameName |
| taxon-id | Taxonomic Concept identifier, note this is currently in testname-short | Country Short Name |
| name-long | Country Long Name |
| local-abbrev| Local Abbreviation |
h3. Example Responses
h4. CSV
{noformat}
Rhea americana,Greater Rhea,TC000004
Rhea pennata,Lesser Rhea, TC000005
{noformat}
h4. XML
{noformat}
<response>
<header>AF,Afghanistan,Afghanistan,Islamic State of Afghanistan,AF
KG,Kyrgyzstan,Kyrgyzstan,Kyrgyz Republic,KG
KZ,Kazakhstan,Kazakhstan,Republic of Kazakhstan,KZ
PK,Pakistan,Pakistan,Islamic Republic of Pakistan,PK
SH,"Saint Helena, Ascension, and Tristan da Cunha",Saint Helena,Saint Helena,SH
TJ,Tajikistan,Tajikistan,Republic of Tajikistan,TJ
TM,Turkmenistan,Turkmenistan,Turkmenistan,TM
UZ,Uzbekistan,Uzbekistan,Republic of Uzbekistan,UZ
{noformat}
h4. XML
{noformat}
<response>
<header>
<locale country="" language="en"/>
<timestamp>2014-04-03T11:49:34.291-04:00</timestamp>
<criteria find-command-flag="true">
<fmt>xml</fmt>
<match>stan</match>
<region-type>country</region-type>
<rtype>country</rtype>
</criteria>
</header>
<result>
<country>
<country-code>AF</country-code>
<name>Afghanistan</name>
<name-short>Afghanistan</name-short>
<name-long>Islamic State of Afghanistan</name-long>
<local-abbrev>AF</local-abbrev>
</country>
<country>
<country-code>KG</country-code>
<name>Kyrgyzstan</name>
<name-short>Kyrgyzstan</name-short>
<name-long>Kyrgyz Republic</name-long>
<local-abbrev>KG</local-abbrev>
</country>
<country>
<country-code>KZ</country-code>
<name>Kazakhstan</name>
<locale country="" language="en"/>
<name-short>Kazakhstan</name-short>
<name-long>Republic of <timestamp>Kazakhstan</name-long>
2009-07-08T10:39:42.150-04:00<local-abbrev>KZ</local-abbrev>
</timestamp>country>
<country>
<criteria>
<country-code>PK</country-code>
<locale country="" language="en"/> <name>Pakistan</name>
<cat>
<name-short>Pakistan</name-short>
<name-long>Islamic Republic speciesof Pakistan</name-long>
</cat><local-abbrev>PK</local-abbrev>
</country>
<fmt><country>
<country-code>SH</country-code>
xml
<name>Saint Helena, Ascension, and Tristan da Cunha</name>
</fmt>
</criteria>
<name-short>Saint Helena</name-short>
</header>
<result>
<name-long>Saint <taxa>
Helena</name-long>
<com-name><local-abbrev>SH</local-abbrev>
</country>
Greater<country>
Rhea
<<country-code>TJ</comcountry-name>code>
<sci- <name>Tajikistan</name>
<name-short>Tajikistan</name-short>
Rhea americana
<name-long>Republic of <Tajikistan</sciname-name>long>
<taxon-id> <local-abbrev>TJ</local-abbrev>
</country>
TC00000004<country>
<<country-code>TM</taxoncountry-id>code>
</taxa>
<taxa><name>Turkmenistan</name>
<com-name> <name-short>Turkmenistan</name-short>
<name-long>Turkmenistan</name-long>
Lesser Rhea
<local-abbrev>TM</local-abbrev>
</com-name>country>
<country>
<sci-name>
<country-code>UZ</country-code>
Rhea pennata<name>Uzbekistan</name>
<<name-short>Uzbekistan</sciname-name>short>
<taxon <name-id>
long>Republic of Uzbekistan</name-long>
TC00000005
<local-abbrev>UZ</local-abbrev>
</taxon-id>country>
</taxa>result>
</response>
{noformat}
h2. Subnational1 Result Fields
|| *Field (XML)* || *Description* ||
| country-code | Country Code |
| subnational1-code | Subnational1 Code |
| name | Full Name of Subnational1 Entity |
| local-abbrev | Local Abbreviation |
h3. Example Responses
h4. CSV
{noformat}
CV,CV-,Cape Verde,
CV,CV-B,Ilhas de Barlavento,B
CV,CV-S,Ilhas de Sotavento,S
{noformat}
h4. XML
{noformat}
<response>
<header>
<locale country="" language="en"/>
<timestamp>2014-04-03T11:22:00.416-04:00</timestamp>
<criteria find-command-flag="false">
<region-code>CV</region-code>
<region-codes>CV</region-codes>
<fmt>xml</fmt>
<country-code>CV</country-code>
<region-type>subnational1</region-type>
<rtype>subnational1</rtype>
</criteria>
</header>
<result>
<subnational1>
<country-code>CV</country-code>
<subnational1-code>CV-</subnational1-code>
<name>Cape Verde</name>
</subnational1>
<subnational1>
<country-code>CV</country-code>
<subnational1-code>CV-B</subnational1-code>
<name>Ilhas de Barlavento</name>
<local-abbrev>B</local-abbrev>
</subnational1>
<subnational1>
<country-code>CV</country-code>
<subnational1-code>CV-S</subnational1-code>
<name>Ilhas de Sotavento</name>
<local-abbrev>S</local-abbrev>
</subnational1>
</result>
</response>
{noformat}
h2. 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 |
h3. Example Responses
h4. CSV
{noformat}
Rhea americana,Greater Rhea,TC000004
Rhea pennata,Lesser Rhea, TC000005
{noformat}
h4. XML
{noformat}
<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>
{noformat}
h2. Caching Information
For details on caching of results by our servers, see [eBird-1.1-CacheInformation|eBird-1.1-CacheInformation]
{import:eBird-footer} |
