*** This version of Confluence is for testing only and contains a copy of content from June 29th 2026. No changes will be preserved. ***
eBird Hot Spot List - Version 1.0
| Panel | ||||
|---|---|---|---|---|
|
Summary
eBird Hot Spot List Web Service API
API
This functionality is contained in the IS/DataDelivery code base.
Get a list of eBird hotspots, for a state or for a country. The eBird Hot Spots Examples page contains links for this API for each state and province in the US and Canada.
API
URI URL | description | status | notes |
|---|---|---|---|
ws ws1.0/data/hotspot/list?countryCode=<2-letter ISO country code> | Return list of hotspots found in the given country | coded and deployed |
|
ws 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 and or subnational1Code is required | n/a | see CountryCode List and Search Web Service API AKN-1.0-Country | coded and deployed | |
subnational1Code | one of countryCode and or subnational1Code is required | n/a | see Subnational1Code List and Search Web Service APIAKN-1.0-Subnational1 | coded and deployed | |
format | no | csv | csv , xml | format to use for response; this parameter is case sensitive | coded and deployed |
Test URLS
Development URL | Deployed URL | Expected Response | Notes | ||||
|---|---|---|---|---|---|---|---|
http://localhostebird.org/ws1.0/data/hotspot/list?countryCode= |
| empty list in CSV format |
| ||||
http://localhostebird.org/ws1.0/data/hotspot/list?countryCode=US | list in CSV format | Country code in uppercase is valid. | |||||
http://localhostebird.org/ws1.0/data/hotspot/list?countryCode=us |
| empty list in CSV format | Country code in lowercase is invalid. | ||||
http://localhostebird.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://localhostebird.org/ws1.0/data/hotspot/list?countryCode=US&format=csv |
| list in CSV format |
| ||||
http://localhostebird.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://localhostebird.org/ws1.0/data/hotspot/list?countryCode=US&format=qqq |
| list in CSV format | Bad format value is ignored and defaults to "csv". | ||||
[][http://localhostebird.org/ws1.0/data/hotspot/list?subnational1Code=] |
| empty list in CSV format | ]]></ac:plain-text-body></ac:structured-macro> | <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="dba3037a-bd07-4a92-89b0-c95bcf4f19fc"><ac:plain-text-body><![CDATA[ | |||
http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-FL | http://ebird.org [][http://localhost/ws1.0/data/hotspot/list?subnational1Code=US-FL] | list in CSV format | Subnational1 code in uppercase is valid. | ||||
]]></ac:plain-text-body></ac:structured-macro> | <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="172c273a-8538-4505-b9de-c4bc2014cbb8"><ac:plain-text-body><![CDATA[ | [][http://localhostebird.org/ws1.0/data/hotspot/list?subnational1Code=us-fl] |
| empty list in CSV format | Subnational1 code in lowercase is invalid. | ]]></ac:plain-text-body></ac:structured-macro> | <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="399d22a2-d028-4c93-a236-446da13aedd5"><ac:plain-text-body><![CDATA[ |
http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-FL&format=xml | http://ebird.org [][][http://localhost/ws1.0/data/hotspot/list?subnational1Code=US-FL&format=xml] |
| list in XML format | ]]></ac:plain-text-body></ac:structured-macro> |
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.
CSV Result Format
| Panel |
|---|
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>" |
...
| Panel |
|---|
L453718, US, US-RI, 41.3302, -71.8375, "Avondale Farm" |
XML Result Format
Example
| No Format |
|---|
<?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>
|
Potential Improvements
- Add summary info to each record:
- # of checklists per hotspot
- Add KML format option to produce GoogleEarth/Map compatible files.
| Wiki Markup |
|---|
{import:eBird-footer} |