Page History

{panel}
{toc:minlevel=2}
{panel}

h2. Summary

Get a list of [eBird hotspots|http://ebird.org/content/ebird/about/hotspots],  for a state or for a country. The [eBird Hot Spots Examples|eBird-1.0-HotSpots-Example] page contains links for this API for each state and province in the US and Canada.

h2. API

|| URI || description || status || notes ||
| ws1.0/data/hotspot/list?countryCode=<2-letter ISO country code>

 | Return list of hotspots found in the given

 country \\ | coded and deployed | |
| ws1.0/data/hotspot/list?subnational1Code=<subnational1

 code> \\ | Return list of hotspots names found in the given "state" | coded and deployed \\ | |

|| parameter || required || default || value options \\ || description || status ||
| countryCode | one of countryCode or subnational1Code is required \\ | n/a | \\ | see [AKN-1.0-Country

] | coded and deployed

 |
| subnational1Code | one of countryCode or subnational1Code is required | n/a | \\ | see [AKN-1.0-Subnational1

]\\ | coded and deployed |
| format | no | csv \\ | csv, xml | format to use for response; this parameter is case sensitive \\ | coded and deployed  |

h2. Test URLS

|| Development URL || Deployed URL || Expected Response || Notes ||
| [http://ebird.org/ws1.0/data/hotspot/list?countryCode=

] | | empty list in CSV format \\ | |
| [http://ebird.org/ws1.0/data/hotspot/list?countryCode=US

] | [http://ebird.org/ws1.0/data/hotspot/list?countryCode=US

] | list in CSV

 format \\ | Country code in uppercase is valid. \\ |
| [http://ebird.org/ws1.0/data/hotspot/list?countryCode=us

] | | empty list in CSV format \\ | Country code in lowercase is invalid. \\ |
| [http://ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=xml

] | [http://ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=xml

] | list in XML

 format \\ | |
| [http://ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=csv

] | | list in CSV format \\ | |
| [http://ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=XML

] | | list in CSV format | "XML" is not a valid format option. Only "xml" and "csv" are valid options. An invalid option will default to "csv" format.

 \\ |
| [http://ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=qqq

] | | list in CSV format \\ | Bad format value is ignored and defaults to "csv". \\ |
| [http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=

] | | empty list in CSV format | \\ |
| [http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-FL

] | [http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-FL

] | list in CSV

 format \\ | Subnational1 code in uppercase is valid. \\ |
| [http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=us-fl

] | | empty list in CSV format | Subnational1 code in lowercase is invalid. \\ |
| [http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-FL&format=xml

] | [http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-FL&format=xml

] | list in XML

 format | |
\\

h2. Caching

Responses to this API are cached up to 24 hours hours on our servers. Because of this, API consumers might see inconsistencies between various calls submitted at the same time (e.g. a particular US-VA hot spot is included in the response to a request for all the US-VA hot spots, but it is not included in a request submitted at the same time listing all the US hot spots). In the XML response format, the time stamp in the header section shows the time that the response was originally created, and so API consumers can see the age of the particular response.

h2. CSV Result Format

{panel}

h2. XML Result Format

*Example*
{noformat}
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <header>
        <locale country="US" language="en"/>
        <timestamp>2008-07-25T10:54:16.432-04:00</timestamp>
        <criteria>
            <property id="subnational11Code" value="US-RI" description="Rhode Island"/>
        </criteria>
        <comment/>
    </header>
    <result>
        <hotspot>
            <loc-id>L453718</loc-id>
            <location>Avondale Farm</location>
            <longitude>-71.8375</longitude>
            <latitude>41.3302</latitude>
            <subnational1-code>US-RI</subnational1-code>
            <country-code>US</country-code>
        </hotspot>
        <hotspot>
            <loc-id>L231740</loc-id>
            <location>Beavertail State Park</location>
            <longitude>-71.3987547</longitude>
            <latitude>41.4496915</latitude>
            <subnational1-code>US-RI</subnational1-code>
            <country-code>US</country-code>
        </hotspot>
    </result>
</response>

{noformat}

h2. Potential Improvements

* Add summary info to each record:
** \# of checklists per hotspot
* Add KML format option to produce GoogleEarth/Map compatible files.

{import:eBird-footer}