Description
Returns the most recent sighting date and specific location for each species of bird reported within the number of days specified by the "back" parameter and reported at birding hotspots.
This is part of the eBird version 1.1 API.
URL
Base URL
http://ebird.org/ws1.1/data/obs/hotspot/recent
Examples
Minimal:
http://ebird.org/ws1.1/data/obs/hotspot/recent?r=L99381
Fully specified:
Parameter Descriptions
Parameter Name |
Required |
Default |
Value Options |
Example Value |
Description |
|---|---|---|---|---|---|
back |
|
14 |
1 - 30 integer |
7 |
the number of days back to look for observations |
maxResults |
|
|
1 - 10000 integer |
10 |
the maximum number of result rows to return in this request; to get all results do not include this parameter |
detail |
|
simple |
simple, full |
simple |
toggle to restrict results to either all or a subset of sighting fields. see result field descriptions |
locale |
|
en_US |
Java standard locale codes |
fr_CA |
Language/locale of response (when translations are available). See http://java.sun.com/javase/6/docs/api/java/util/Locale.html. |
fmt |
|
xml |
json, xml |
json |
format of the response |
r |
yes |
|
any hotspot locID |
L99381 |
Code(s) for region of interest; here, regions are the locIDs of hotspots. LocIDs that are not valid or are not hotspots are ignored. Maximum of 10 locIDs. |
includeProvisional |
|
false |
true,false |
false |
set to true if you'd like flagged records that have not yet been reviewed to be included in the results |
Simple Result Fields
Field (JSON) |
Field (XML) |
Description |
|---|---|---|
comName |
com-name |
species common name. not included in the 'simple' detail if a scientific name was specified as an input parameter |
sciName |
sci-name |
species scientific name. not included in the 'simple' detail if a scientific name was specified as an input parameter |
obsDt |
obs-dt |
observation date formatted according to ISO 8601 (e.g. 'YYYY-MM-DD', or 'YYYY-MM-DD hh:mm'). Hours and minutes are excluded if the observer did not report an observation time. |
howMany |
how-many |
The number observed. Not included if only presence was noted |
locID |
loc-id |
unique identifier for the location |
locationPrivate |
location-private |
'true' if location is not a birding hotspot. 'false' otherwise |
locName |
loc-name |
location name |
lat |
lat |
latitude of the location |
lng |
lng |
longitude of the location |
obsReviewed |
obs-reviewed |
'true' if obs has been reviewed. 'false' otherwise |
obsValid |
obs-valid |
'true' if obs has been deemed valid by either the automatic filters or a regional reviewer. 'false' otherwise |
Example Responses
XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<header>
<locale country="US" language="en"/>
<timestamp>
2009-07-01T10:29:53.035-04:00
</timestamp>
<criteria>
<command>
<fmt>
xml
</fmt>
<include-provisional>
true
</include-provisional>
<r>
L99381
</r>
<back>
30
</back>
<max-results>
500
</max-results>
<detail>
simple
</detail>
</command>
</criteria>
</header>
<result>
<sighting>
<loc-id>
L99381
</loc-id>
<obs-dt>
2009-06-24 17:00
</obs-dt>
<obs-reviewed>
false
</obs-reviewed>
<obs-valid>
true
</obs-valid>
<loc-name>
Stewart Park
</loc-name>
<how-many>
1
</how-many>
<lat>
42.4613266
</lat>
<lng>
-76.5059255
</lng>
<com-name>
Barn Swallow
</com-name>
<sci-name>
Hirundo rustica
</sci-name>
</sighting>
</result>
</response>
JSON
[{
"locID": "L99381",
"lat": 42.4613266,
"howMany": 1,
"locName": "Stewart Park",
"obsValid": true,
"lng": -76.5059255,
"sciName": "Hirundo rustica",
"obsReviewed": false,
"obsDt": "2009-06-24 17:00",
"comName": "Barn Swallow"
}]
Full Result Fields
In addition to the fields above, these fields are included in the response when full detail is requested:
Field (JSON) |
Field (XML) |
Description |
|---|---|---|
subnational2Code |
subnational2-code |
county code |
subnational2Name |
subnational2-name |
county name |
subnational1Code |
subnational1-code |
state/province ISO code |
subnational1Name |
subnational1-name |
state/province name |
countryCode |
country-code |
country ISO code |
userDisplayName |
user-display-name |
first and last name of the observer, when available |
countryName |
country-name |
country name |
firstName |
first-name |
observer's first name, when available (DEPRECATED in favor of userDisplayName) |
lastName |
last-name |
observer's last name, when available (DEPRECATED in favor of userDisplayName) |
subID |
sub-id |
submission ID |
obsID |
obs-id |
observation ID |
checklistID |
checklist-id |
checklist ID |
presenceNoted |
presence-noted |
'true' if user marked presence but did not count the number of birds. 'false' otherwise |
Example Responses
Note that "full" detail nearly triples the size of the response on average.
XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<header>
<locale country="US" language="en"/>
<timestamp>
2009-07-01T11:26:06.296-04:00
</timestamp>
<criteria>
<fmt>
xml
</fmt>
<hotspot>
false
</hotspot>
<rtype>
subnational1
</rtype>
<r>
US-NY
</r>
<back>
5
</back>
<max-results>
500
</max-results>
<detail>
full
</detail>
</criteria>
</header>
<result>
<sighting>
<sub-id>
S5130155
</sub-id>
<obs-id>
OBS72270247
</obs-id>
<checklist-id>
CL22361
</checklist-id>
<loc-id>
L285876
</loc-id>
<presence-noted>
false
</presence-noted>
<location-private>
true
</location-private>
<country-name>
United States
</country-name>
<country-code>
US
</country-code>
<subnational2-name>
Richmond
</subnational2-name>
<subnational2-code>
US-NY-085
</subnational2-code>
<first-name>
Catherine
</first-name>
<subnational1-name>
New York
</subnational1-name>
<last-name>
Barron
</last-name>
<subnational1-code>
US-NY
</subnational1-code>
<obs-dt>
2009-06-30 13:30
</obs-dt>
<obs-reviewed>
false
</obs-reviewed>
<obs-valid>
false
</obs-valid>
<loc-name>
SI-South Beach/Ft Wadsworth
</loc-name>
<how-many>
2
</how-many>
<lat>
40.6028326
</lat>
<lng>
-74.0537782
</lng>
<com-name>
Red-throated Loon
</com-name>
<sci-name>
Gavia stellata
</sci-name>
</sighting>
</result>
</response>
JSON
[{
"locID": "L285876",
"locationPrivate": true,
"checklistID": "CL22361",
"obsValid": false,
"presenceNoted": false,
"countryCode": "US",
"subnational1Name": "New York",
"subnational1Code": "US-NY",
"lastName": "Barron",
"lat": 40.6028326,
"howMany": 2,
"firstName": "Catherine",
"sciName": "Gavia stellata",
"subnational2Name": "Richmond",
"subnational2Code": "US-NY-085",
"obsReviewed": false,
"comName": "Red-throated Loon",
"obsID": "OBS72270247",
"locName": "SI-South Beach/Ft Wadsworth",
"lng": -74.0537782,
"subID": "S5130155",
"obsDt": "2009-06-30 13:30",
"countryName": "United States"
}]
Special Conditions and Error Handling
If there are validation problems with the input parameters the response will have an appropriate HTTP status code (e.g., 400) and details of the problem will be provided in the result format requested (JSON or XML).
Error Responses
XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<header>
<locale country="US" language="en"/>
<timestamp>
2009-07-01T10:45:34.758-04:00
</timestamp>
<criteria>
<command>
<fmt>
xml
</fmt>
<include-provisional>
true
</include-provisional>
<r>
L99381
</r>
<back>
320
</back>
<max-results>
500
</max-results>
<detail>
simple
</detail>
</command>
</criteria>
<errors>
<error>
<error-msg>
The maximum number of days back is 30
</error-msg>
<error-code>
error.data.too_many_back
</error-code>
</error>
</errors>
</header>
<result/>
</response>
JSON
The response will include a simple array containing details of the problems encountered:
[{
"errorMsg": "The maximum number of days back is 30",
"errorCode": "error.data.too_many_back"
}]
Current List of Error Messages
This list may change or be added to at any time. Items in brackets will be specified at the time the message is received.
error.data.dist_out_of_range = Distance must be between {0} and {1}
error.data.lat_out_of_range = Latitude out of range
error.data.lng_out_of_range = Longitude out of range
error.data.lat_required = Parameter 'lat' is required
error.data.lng_required = Parameter 'lng' is required
error.data.rcodes_required = Please specify a region code
error.data.rtype_required = The parameter 'rtype' for region type is required
error.data.rcodes_toomany = Too many region codes. Please limit your selection to {0} region codes.
error.data.too_many_back = The maximum number of days back is {0}
error.data.too_few_back = Please specify a number of days back greater than zero.
error.data.too_many_results = Please specify a "maxResults" parameter greater than {0}.
error.data.too_few_results = Please specify a "maxResults" parameter less than or equal to {0}.
error.data.unknown_species = Unknown species: {0}
error.data.sci_required = Please specify the scientific name of the species of interest with the parameter 'sci'.
error.data.unsupported_detail = Sorry, the "{0}" detail is not currently supported for this service.
error.data.unsupported_rtype = Sorry, the region type "{0}" is not currently supported for this service.
error.unsupported_fmt = Sorry, {0} format is not currently supported for this service.
Caching Information
For details on caching of results by our servers, see eBird-1.1-CacheInformation
Unknown macro: {import}