Versions Compared

Old Version 9

changes.mady.by.user user-2d3e8

Saved on

compared with

New Version 10

changes.mady.by.user user-2d3e8

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Wiki Markup
{toc}

h2. Description

Returns location-based look-up data based on the rtype (Region Type) parameter; rtype options are: *bcr*, *country*, *subnational1*, and *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 ||
| 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* \\ |


h2. BCR Result Fields

|| *Field (XML)* || *Description* ||
| sciprimary-name | ScientificBCR name |
| com-Primary name | Common name |
| taxonregion-idcode | Taxonomic Concept identifier, note this is currently in test BCR code |

h3. Example Responses


h4. CSV

{noformat}
Rhea americana,Greater Rhea,TC000004
Rhea pennata,Lesser Rhea, TC000005West 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>
            2009-07-08T10:39:42.150-04:00
        </timestamp>
        <criteria>
            <locale country="" language="en"/>
            <cat>
              <locale  speciescountry="" language="en"/>
      <timestamp>2014-04-03T11:37:01.761-04:00</timestamp>
       </cat><criteria find-command-flag="true">
         <fmt>xml</fmt>
   <fmt>
      <match>coast</match>
          xml<region-type>bcr</region-type>
            </fmt>
 <rtype>bcr</rtype>
       </criteria>
    </header>
    <result>
    <taxa>
        <com-name><location>
         <primary-name>West Gulf  Greater Rhea
Coastal Plain/Ouachitas</primary-name>
         <<region-code>25</comregion-name>code>
        <sci-name></location>
      <location>
      Rhea americana
        </sci<primary-name>Southeastern Coastal Plain</primary-name>
         <taxon-id><region-code>27</region-code>
      </location>
      TC00000004<location>
         <primary-name>New <England/taxonMid-id>
    </taxa>atlantic Coast</primary-name>
    <taxa>
        <com-name>
<region-code>30</region-code>
      </location>
      <location>
 Lesser Rhea
       <primary-name>Coastal <California</comprimary-name>
        <sci-name> <region-code>32</region-code>
      </location>
      <location>
  Rhea pennata
      <primary-name>Gulf Coastal <Prairie</sciprimary-name>
         <taxon-id>
            TC00000005
<region-code>37</region-code>
         </taxon-id>location>
    </taxa>result>
</response>
{noformat}

h2. Country 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>
            2009-07-08T10:39:42.150-04:00
        </timestamp>
        <criteria>
            <locale country="" language="en"/>
            <cat>
                species
            </cat>
            <fmt>
                xml
            </fmt>
        </criteria>
    </header>
    <result>
    <taxa>
        <com-name>
            Greater Rhea
        </com-name>
        <sci-name>
            Rhea americana
        </sci-name>
        <taxon-id>
            TC00000004
        </taxon-id>
    </taxa>
    <taxa>
        <com-name>
            Lesser Rhea
        </com-name>
        <sci-name>
            Rhea pennata
        </sci-name>
        <taxon-id>
            TC00000005
        </taxon-id>
    </taxa>
</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* ||
| 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>
            2009-07-08T10:39:42.150-04:00
        </timestamp>
        <criteria>
            <locale country="" language="en"/>
            <cat>
                species
            </cat>
            <fmt>
                xml
            </fmt>
        </criteria>
    </header>
    <result>
    <taxa>
        <com-name>
            Greater Rhea
        </com-name>
        <sci-name>
            Rhea americana
        </sci-name>
        <taxon-id>
            TC00000004
        </taxon-id>
    </taxa>
    <taxa>
        <com-name>
            Lesser Rhea
        </com-name>
        <sci-name>
            Rhea pennata
        </sci-name>
        <taxon-id>
            TC00000005
        </taxon-id>
    </taxa>
</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}