Versions Compared

Old Version 72

changes.mady.by.user user-2d3e8

Saved on

compared with

New Version Current

changes.mady.by.user user-2d3e8

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Table of Contents

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

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

XML

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

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

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

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

XML

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

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

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

Wiki Markup
{import:eBird-footer}