eBird Hot Spot List Web Service API - Version 1.0

Summary

Get a list of eBird hotspots,  for a state or for a country.

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 

Test URLS

Development URL

Deployed URL

Expected Response

Notes

http://localhost/ws1.0/data/hotspot/list?countryCode=

 

empty list in CSV format

 

http://localhost/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://localhost/ws1.0/data/hotspot/list?countryCode=us

 

empty list in CSV format

Country code in lowercase is invalid.

http://localhost/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://localhost/ws1.0/data/hotspot/list?countryCode=US&format=csv

 

list in CSV format

 

http://localhost/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://localhost/ws1.0/data/hotspot/list?countryCode=US&format=qqq

 

list in CSV format

Bad format value is ignored and defaults to "csv".

http://localhost/ws1.0/data/hotspot/list?subnational1Code=

 

empty list in CSV format


http://localhost/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://localhost/ws1.0/data/hotspot/list?subnational1Code=us-fl

 

empty list in CSV format

Subnational1 code in lowercase is invalid.

http://localhost/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

 


CSV Result Format

<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"

Example

 L453718, US, US-RI, 41.3302, -71.8375, "Avondale Farm"
L231740, US, US-RI, 41.4496915, -71.3987547, "Beavertail State Park"
L466297, US, US-RI, 41.3202, -71.8303, "Big Maschaug Pond, Watch Hill"
L490189, US, US-RI, 41.3623801, -71.4880371, "Camp Cronin"
L487743, US, US-RI, 41.8591418, -71.3376617, "Central Pond Reservoir"
L466303, US, US-RI, 41.3571, -71.6374, "Charlestown Breachway"
L166174, US, US-RI, 41.49133, -71.292656, "Easton Pond"
L487669, US, US-RI, 41.7074586, -71.6359663, "Flat River Reservoir"
L357306, US, US-RI, 41.9668934, -71.5573883, "Fort Refuge"
L384479, US, US-RI, 41.4743419, -71.3398933, "Ft. Adams State Park"

XML Result Format

Example

<?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