Versions Compared

Old Version 1

changes.mady.by.user Paul Allen

Saved on

compared with

New Version Current

changes.mady.by.user Anonymous

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

eBird Hot Spot List - Version 1.0

Panel
Table of Contents

Subnational2Code List and Search Web Service API

API

This functionality is contained in the IS/DataDeliveryREST code base.

minlevel2

Summary

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/refdata/subnational2hotspot/list?countryCode=<2-letter ISO country code>

Return list of "county" names hotspots found in the given country

coded , not and deployed

 

ws/ref/subnational2/find?match=<string to match>

Return list of "county" names that match

coded, not deployed

Can wildcards be used in the match string? No wildcard yet implemented.

ws/ref/subnational2 ws1.0/data/hotspot/list?subnational1Code=<subnational1 code>

Return list of "county" hotspots names found in the given "state"

coded , not and deployed

 

not coded

parameter

required

default

value options

description

status

match

yes, for /find

n/a

 

String to match against "county" names. What kind of wildcards can be used?

coded, not deployed. No wildcard yet implemented.

locale

no

en_US

Java standard locale codes

locale in which to perform matching, and in which to provide names in response (when possible)

countryCode

one of countryCode and or subnational1Code is required for /list

n/a


see AKN-1.0-Country

coded and CountryCode List and Search Web Service API coded, not deployed

subnational1Code

one of countryCode and or subnational1Code is required for /list

n/a


see AKN-1.0-Subnational1

coded and Subnational1Code List and Search Web Service API
coded, not deployed

format

no

csv

csv

, xml

format to use for response; this parameter is case sensitive

coded , not deployed and deployed 

Test URLS

 

Development URL

Deployed URL

Expected Response

Notes

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=

 

empty list in CSV format

 

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=

 

empty list in CSV format

 US

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=US

 

entire list in CSV format

Country code in uppercase is valid.

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=us

 

empty list in CSV format

Country code in lowercase is invalid.

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=xml

 

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

entire list in XML format

 

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=csv

 

entire list in CSV format

 

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=XML

 

entire 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/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=US&format=qqq

 

entire list in CSV format

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

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?countryCode=US&formatsubnational1Code=QQQ

 

entire empty list in CSV format

Bad format value is ignored and defaulted to csv.


http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?subnational1Code=

 

empty list in CSV format US-FL

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-NY FL

entire list in CSV format

Subnational1 code in uppercase is valid.

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?subnational1Code=us-nyfl

 

empty list in CSV format

Subnational1 code in lowercase is invalid.

http://localhost/ws/ref/subnational2ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-NYFL&format=xml 

entire list in XML format

 

http://localhost/ws/ref/subnational2/find?match=clay

 

entire list in CSV format

 

http://localhost/ws/ref/subnational2/find?match=CLAY

 

entire list in CSV format

There should be no difference in response for upper/lower case search strings.

ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-FL&format=xml

http://localhost/ws/ref/subnational2/find?match=clay&format=xml

 

entire list in XML format

 

http://localhost/ws/ref/subnational2/find?match=

 

empty list in CSV format


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>, <subnational2 code>, <name associated with subnational2 code>
, <latitude>, <longitude>, "<name>"
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"
<loc ID>, <country code>, <subnational1 code>, <latitude>, <subnational2 code>, <name associated with subnational2 code
<country code>, <subnational1 code>, <subnational2 code>, <name associated with subnational2 code>

XML Result Format

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

Example

Panel

 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

No Format

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <header>
No Format

<response>
  <header>
    <locale country="US" language="en"/>
        <timestamp>2008-0207-21T1225T10:3754:3216.546432-0504:00</timestamp>
        <criteria>
            <property nameid="matchsubnational11Code" value="seomthingUS-RI" description="Rhode Island"/>
      <property name="subnational1Code" value="seomthing"/> </criteria>
      <property name="countryCode" value="seomthing" <comment/>
    </criteria>
    <comment>
    </comment>
  </header>
  <result>
    <location countryCode="" subnational1Code="" subnational2Code="">name of the subnational2 region </location>
    <location countryCode="" subnational1Code="" subnational2Code="">name of the subnational2 region </location>
    <location countryCode="" subnational1Code="" subnational2Code="">name of the subnational2 region </location>
    <location countryCode="" subnational1Code="" subnational2Code="">name of the subnational2 region </location>
/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}