Wiki Markup |
---|
{toc} h2. Description Returns location-based look-up data based on the rtype (Region Type) parameter; rtype options are: *bcr*, *country*, *subnational1*, andor *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} |
Page History
Overview
Content Tools