{toc}

h2. Description

Returns location-based look-up data based on the rtype (Region Type) parameter; rtype options are: *bcr*, *country*, *subnational1*, or *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 ||
| rtype \\ | yes \\ | none \\ | bcr, country, subnational1, or subnational2 \\ | country \\ | region type parameter \\ |
| 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* \\ |
| match \\ | yes for *find* request \\ | none \\ | Any whole word or partial word stub \\ | south \\ | required for *find* request, key for primary name record matching \\ |


h2. BCR Result Fields

|| *Field (XML)* || *Description* ||
| primary-name | BCR Primary Name |
| region-code | BCR Code |

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* ||
| country-code | Country Code |
| name | Country Name |
| name-short | Country Short Name |
| name-long | Country Long Name |
| local-abbrev | Local Abbreviation |

h3. Example Responses


h4. CSV

{noformat}
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>
         <name-short>Kazakhstan</name-short>
         <name-long>Republic of Kazakhstan</name-long>
         <local-abbrev>KZ</local-abbrev>
      </country>
      <country>
         <country-code>PK</country-code>
         <name>Pakistan</name>
         <name-short>Pakistan</name-short>
         <name-long>Islamic Republic of Pakistan</name-long>
         <local-abbrev>PK</local-abbrev>
      </country>
      <country>
         <country-code>SH</country-code>
         <name>Saint Helena, Ascension, and Tristan da Cunha</name>
         <name-short>Saint Helena</name-short>
         <name-long>Saint Helena</name-long>
         <local-abbrev>SH</local-abbrev>
      </country>
      <country>
         <country-code>TJ</country-code>
         <name>Tajikistan</name>
         <name-short>Tajikistan</name-short>
         <name-long>Republic of Tajikistan</name-long>
         <local-abbrev>TJ</local-abbrev>
      </country>
      <country>
         <country-code>TM</country-code>
         <name>Turkmenistan</name>
         <name-short>Turkmenistan</name-short>
         <name-long>Turkmenistan</name-long>
         <local-abbrev>TM</local-abbrev>
      </country>
      <country>
         <country-code>UZ</country-code>
         <name>Uzbekistan</name>
         <name-short>Uzbekistan</name-short>
         <name-long>Republic of Uzbekistan</name-long>
         <local-abbrev>UZ</local-abbrev>
      </country>
   </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* ||
| country-code | Country Code |
| subnational1-code | Subnational1 Code |
| subnational2-code | Subnational2 Code |
| name | Name |

h3. Example Responses


h4. CSV

{noformat}
CA,CA-AB,CA-AB-EI,Red Deer
CA,CA-AB,CA-AB-EL,Edmonton
CA,CA-AB,CA-AB-ET,Grande Cache
CA,CA-AB,CA-AB-FI,Drumheller
CA,CA-AB,CA-AB-FN,Banff
CA,CA-AB,CA-AB-FO,Hanna
CA,CA-AB,CA-AB-FT,Edson
CA,CA-AB,CA-AB-NI,Rocky Mountain House
CA,CA-AB,CA-AB-NT,Grande Prairie
CA,CA-AB,CA-AB-ON,Medicine Hat
CA,CA-AB,CA-AB-SE,Stettler
CA,CA-AB,CA-AB-SI,Calgary
CA,CA-AB,CA-AB-SN,Slave Lake
CA,CA-AB,CA-AB-ST,Fort McMurray
CA,CA-AB,CA-AB-TE,Camrose-Lloydminister
CA,CA-AB,CA-AB-TN,Athabasca
CA,CA-AB,CA-AB-TR,Fort MacLeod
CA,CA-AB,CA-AB-TV,St. Paul
CA,CA-AB,CA-AB-TW,Lethbridge
{noformat}

h4. XML

{noformat}
<response>
   <header>
      <locale country="" language="en"/>
      <timestamp>2014-04-03T13:10:45.096-04:00</timestamp>
      <criteria find-command-flag="false">
         <region-code>CA-AB</region-code>
         <region-codes>CA-AB</region-codes>
         <fmt>xml</fmt>
         <region-type>subnational2</region-type>
         <rtype>subnational2</rtype>
         <subnational1-code>CA-AB</subnational1-code>
      </criteria>
   </header>
   <result>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-EI</subnational2-code>
         <name>Red Deer</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-EL</subnational2-code>
         <name>Edmonton</name>
      </subnational2>
      <subnational2>
            <country-code>CA</country-code>
            <subnational1-code>CA-AB</subnational1-code>
            <subnational2-code>CA-AB-ET</subnational2-code>
            <name>Grande Cache</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-FI</subnational2-code>
         <name>Drumheller</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-FN</subnational2-code>
         <name>Banff</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-FO</subnational2-code>
         <name>Hanna</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-FT</subnational2-code>
         <name>Edson</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-NI</subnational2-code>
         <name>Rocky Mountain House</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-NT</subnational2-code>
         <name>Grande Prairie</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-ON</subnational2-code>
         <name>Medicine Hat</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-SE</subnational2-code>
         <name>Stettler</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-SI</subnational2-code>
         <name>Calgary</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-SN</subnational2-code>
         <name>Slave Lake</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-ST</subnational2-code>
         <name>Fort McMurray</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-TE</subnational2-code>
         <name>Camrose-Lloydminister</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-TN</subnational2-code>
         <name>Athabasca</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-TR</subnational2-code>
         <name>Fort MacLeod</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-TV</subnational2-code>
         <name>St. Paul</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-TW</subnational2-code>
         <name>Lethbridge</name>
      </subnational2>
   </result>
</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}