Page History

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>
      taxa/ebird?cat=species&fmt=xml&locale=en_US]

h2. Parameter Descriptions

|| Parameter Name || Required || Default || Value Options || Example Value || Description ||
| cat | no | species | domestic,form,hybrid,intergrade,issf,slash,species,spuh | hybrid | For more info about the meaning of species categories, see [http://ebird.org/content/ebird/about/ebird-taxonomy] |
| locale | no | en_US | fr_CA,es_MX,es_PR,ht_HT,fr,fr_HT,es_CU,es_PA,es_DO,en_NZ,es,es_CL | fr_CA | The locale for the taxon common name |
| fmt \\ | no \\ | csv \\ | xml,csv \\ | xml \\ | |

h3. Resources

The human readable version of the current eBird taxonomy can also be downloaded&nbsp; [here|http://ebird.org/content/ebird/about/ebird-taxonomy].&nbsp;

h2. 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>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>
        <timestamp>
    <name>Ilhas de Barlavento</name>
         <local-abbrev>B</local-abbrev>
      </subnational1>
      <subnational1>
         <country-code>CV</country-code>
         2009<subnational1-07-08T10:39:42.150-04:00code>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>
timestamp>
        <criteria>
            <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>
       <cat>  <region-codes>CA-AB</region-codes>
         <fmt>xml</fmt>
       species
     <region-type>subnational2</region-type>
         <rtype>subnational2</rtype>
         <subnational1-code>CA-AB</subnational1-code>
      </criteria>
   </cat>
header>
   <result>
      <subnational2>
         <fmt><country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         xml<subnational2-code>CA-AB-EI</subnational2-code>
         <name>Red Deer</name>
      </fmt>/subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-EL</subnational2-code>
        </criteria>
 <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>
      </header>
subnational2>
      <subnational2>
      <result>
   <country-code>CA</country-code>
      <taxa>   <subnational1-code>CA-AB</subnational1-code>
        <com-name> <subnational2-code>CA-AB-FI</subnational2-code>
         <name>Drumheller</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
        Greater Rhea
 <subnational2-code>CA-AB-FN</subnational2-code>
         <name>Banff</name>
      </com-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>
        <sci-name>
     <subnational2-code>CA-AB-FT</subnational2-code>
         <name>Edson</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
        Rhea americana
 <subnational2-code>CA-AB-NI</subnational2-code>
         <name>Rocky Mountain House</name>
      </sci-/subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-NT</subnational2-code>
         <name>Grande Prairie</name>
        <taxon-id></subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
        TC00000004
 <subnational2-code>CA-AB-ON</subnational2-code>
         <name>Medicine Hat</name>
      </taxon-id>/subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-SE</subnational2-code>
         <name>Stettler</name>
      </taxa>/subnational2>
      <subnational2>
         <country-code>CA</country-code>
    <taxa>     <subnational1-code>CA-AB</subnational1-code>
        <com-name> <subnational2-code>CA-AB-SI</subnational2-code>
         <name>Calgary</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
   Lesser Rhea
      <subnational2-code>CA-AB-SN</subnational2-code>
         <name>Slave Lake</name>
      </com-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>
        <sci-name>
 <subnational2-code>CA-AB-TE</subnational2-code>
         <name>Camrose-Lloydminister</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
        Rhea pennata
 <subnational2-code>CA-AB-TN</subnational2-code>
         <name>Athabasca</name>
      </sci-/subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
         <subnational2-code>CA-AB-TR</subnational2-code>
         <name>Fort MacLeod</name>
        <taxon-id>
</subnational2>
      <subnational2>
         <country-code>CA</country-code>
         <subnational1-code>CA-AB</subnational1-code>
       TC00000005
  <subnational2-code>CA-AB-TV</subnational2-code>
         </taxon-id>
<name>St. Paul</name>
      </subnational2>
      <subnational2>
         <country-code>CA</country-code>
        </taxa>
</response>
{noformat}

h2. Caching Information

For details on caching of results by our servers, see [ <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
\|eBird-1.1-CacheInformation] {import:eBird-footer}

Page tree

Versions Compared

Old Version 2

New Version Current

Key

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