eBird-1.1-LocationReference

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.

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
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

BCR Result Fields

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

Example Responses

CSV

West Gulf Coastal Plain/Ouachitas,25
Southeastern Coastal Plain,27
New England/Mid-atlantic Coast,30
Coastal California,32
Gulf Coastal Prairie,37

XML

<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>

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

Example Responses

CSV

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

XML

<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>

Subnational1 Result Fields

Field (XML)	Description
country-code	Country Code
subnational1-code	Subnational1 Code
name	Full Name of Subnational1 Entity
local-abbrev	Local Abbreviation

Example Responses

CSV

CV,CV-,Cape Verde,
CV,CV-B,Ilhas de Barlavento,B
CV,CV-S,Ilhas de Sotavento,S

XML

<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>

Subnational2 Result Fields

Field (XML)	Description
country-code	Country Code
subnational1-code	Subnational1 Code
subnational2-code	Subnational2 Code
name	Name

Example Responses

CSV

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

XML

<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>

Caching Information

For details on caching of results by our servers, see eBird-1.1-CacheInformation

Unknown macro: {import}

Page tree

eBird-1.1-LocationReference

Description

URL

Parameter Descriptions

BCR Result Fields

Example Responses

CSV

XML

Country Result Fields

Example Responses

CSV

XML

Subnational1 Result Fields

Example Responses

CSV

XML

Subnational2 Result Fields

Example Responses

CSV

XML

Caching Information