Recent eBird Observations Made Nearby a Location - Version 1.1
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 in the specified area.
This is part of the eBird version 1.1 API.
URL
Base URL
http://ebird.org/ws1.1/data/obs/geo/recent
Examples
Minimal:
http://ebird.org/ws1.1/data/obs/geo/recent?lng=-76.51&lat=42.46
Fully specified:
Parameter Descriptions
Parameter Name |
Required |
Default |
Value Options |
Example Value |
Description |
---|---|---|---|---|---|
lat |
yes |
|
-90.00 - 90.00 decimal |
42.46 |
decimal latitude, two decimal places of precision required |
lng |
yes |
|
-180.00 - 180.00 decimal |
-76.51 |
decimal longitude, two decimal places of precision required |
dist |
|
25 |
0 - 50 integer |
15 |
distance defining radius of interest from given lat/lng in kilometers |
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 |
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 |
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 |
hotspot |
|
false |
true, false |
false |
set to true if results should be limited to sightings at birding hotspots |
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" }]
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
28 Comments
Anonymous
is the 'dist' parameter the radius around the given lat/long?
Paul Allen
Yes, it is. Sorry for the confusion. I've updated the docs.
Anonymous
Is jsonp not provided?
Paul Allen
Sorry, not at this time.
Anonymous
Thanks for the quick reply.
It should only be about 1 or 2 lines of code, but would make life a LOT easier for developers by allowing them to get around the same-origin policy. Also, I heard there is plans to add API access to user lifelists (and patches/yards?). Is there an ETA?
Paul Allen
Thanks for the suggestion about JSONP. We may be able to get to it, but don't hold your breath.
We may be making a life list API available in the future. We will let everybody know when we have concrete information about that.
Anonymous
A solid API (life lists, updating, etc) for eBird would do wonders for the birding community.
If you're interested in volunteers, just let me know who to email. I've got several years of web development experience and have picked up birding as a hobby in the last year or two. I'm sure I could come up with some free time to help out, if interested.
I'm working on some basic Google Maps apps using the existing API ... love it.
Paul Allen
If you develop any gadgets or mobile apps using this API we'd be happy to help publicize them. You can contact us at clois-api@cornell.edu with questions. I'm sure that the eBird project leaders would have ideas for handy gadgets/apps and would love to provide feedback on any that you might be thinking about.
Anonymous
"Returns a list of all bird species seen within a nearby area, along with their most recent sighting date and specific location."
Shouldn't this read "Returns the most recent sighting of each bird species..."
The way it reads it sounds like it would return every sighting of a species within the given time frame, not just the most recent.
Is there an API for returning "a list of every sighting within a nearby area..."?
Jeff A. Gerbracht
Your right, it returns species information which have been seen based on the "back" parameter.
Anonymous
Currently data/obs/geo/recent returns an empty file when using &includeProvisional=true
No problems occur with &includeProvisional=false or if the includeProvisional parameter is omitted (defaulting to false).
We really need unfiltered records. Your attention to this is greatly appreciated. Thanks.
Paul Allen
We are looking into this. Thanks for letting us know about this issue.
Would you mind sharing the application/gadget you are using this API for?
Jeff A. Gerbracht
Can you try this again, and let us know if you're now seeing data.
Thanks
Anonymous
I am still seeing this issue. Here is the query I sent:
http://ebird.org/ws1.1/data/obs/geo/recent?lng=-105.37&lat=40.04&dist=32&back=30&maxResults=10000&locale=en_US&fmt=xml&includeProvisional=true
I get no results back from this. The browser spins for a while, then just returns nothing to the screen.
Bryan
Anonymous
I just started playing around with Google Maps integration. http://birding.timothyaaron.com/nearest
I think I'll start playing around with a sightings webapp, 1) for more complete access to my own personal sightings, and 2) for a simpler/on-the-trail input method (with export/import to eBird). I'll let you know when it's decent.
Anonymous
(My drop-down list is currently your API species list filtered to only show those also listed on the BNA site. I'm also pulling the images from wikipedia (and linking to the wiki page).)
Anonymous
I am using this function to produce an xml file with this URL: http://ebird.org/ws1.1/data/obs/geo/recent?lng=-105.37&lat=40.04&dist=32&back=1&maxResults=10000&includeProvisional=true&fmt=xml
The response includes observations that I have recently made on Feb 28th. The problem is some of my observations are not showing up in the xml file despite others from the same exact submission showing up. I thought maybe it was unreviewed sightings didn't get in, but the includeProvisional flag was set to true, so that didn't answer my question. Then I wondered about the above comment saying it was the most recent sightings only. So, I checked the rest of the xml file for "Mallard" which I observed and no other records showed up for this, including mine. So, what exactly is happening. There should be 13 sightings from within three different submissions, but only 7 of the observations are showing up. Is this associated with the regional coordinator not accepting some of the sightings into the database or is the API misbehaving or am I interpreting the code improperly?
Thanks for any help in advance.
Bryan
Paul Allen
Thanks for the note. Could you send your name and the details of the submissions in question (date, location) to clois-api@cornell.edu? We'll look into it.
Anonymous
I've noticed that the records come back with the most recent observations first but the order within a date/time seems arbitrary. Do you have any recommendations for sorting these records or is there any way to have them come back sorted taxonomically ?
Anonymous
Could it ever be possible to request detail=full for this API?
Anonymous
The http://ebird.org/ws1.1/data/notable/geo/recent API allows for a distance of up to 250 Km. However, this URL is still restricted to 50Km.
This makes it difficult for an app to have a single distance setting for both searches.
Will this URL and the others also be expanded?
Anonymous
I have a query that omits my observation of Gray Vireo if I just expand the dist from 2 to 25, using the same center coordinates. For example:
http://ebird.org/ws1.1/data/obs/geo/recent?lng=-111.4712&lat=33.8654&dist=25&back=5&locale=en_US&fmt=json&includeProvisional=true
reports a Gray Vireo at Mt. Ord, but not at: US-AZ-Rio Verde - 33.8654x-111.4712 - Apr 23, 2013, 9:43 AM
If I shrink the dist to not include Mt. Ord, e.g.:
http://ebird.org/ws1.1/data/obs/geo/recent?lng=-111.4712&lat=33.8654&dist=2&back=5&locale=en_US&fmt=json&includeProvisional=true
then my observation shows up. (Gray Vireo, 2013-04-23 09:44, 1, location: US-AZ-Rio Verde - 33.8654x-111.4712 - Apr 23, 2013, 9:43 AM
Is this a bug or am I missing something?
Anonymous
Second link has bad characters in it. This is the link with dist=2:
ebird.org/ws1.1/data/obs/geo/recent?lng=-111.4712&lat=33.8654&dist=2&back=5&locale=en_US&fmt=json&includeProvisional=true
Anonymous
I played around with this some more:
http://ebird.org/ws1.1/data/obs/geo/recent?lng=-111.4712&lat=33.8654&dist=7&back=5&locale=en_US&fmt=json&includeProvisional=true
yields:
Change to dist=8:
http://ebird.org/ws1.1/data/obs/geo/recent?lng=-111.4712&lat=33.8654&dist=8&back=5&locale=en_US&fmt=json&includeProvisional=true
and my record disappears, but the Mt. Ord record on same day is returned:
It seems like the record is removed, possibly having something to do with a nearby sighting on the same day?
Anonymous
I'm using the API, in combination with CSV output of life lists, to get a sense for the best places to visit on a weekend when I have some time. ( https://github.com/johnath/ebird )
For this, it would be really helpful if there were a way to get *all* recent sightings, instead of just one per species. Is that possible?
Anonymous
Hello,
I'm using this api for an app that reports the recent sightings in a given location, and I'm wondering how promptly users' sightings are added to the database....in other words, how "real time" is it? Does the database receive new information every minute, hour, day, etc?
Thanks,
Alex
user-ad27b
Please see https://confluence.cornell.edu/display/CLOISAPI/eBird-1.1-CacheInformation for information on update frequency.
Anonymous
Here's another vote for full detail.
My desire revolves around having access to (limited) data without Internet connection. I'm thinking along the lines of a mobile app that tells me a record of who has seen what. Then maybe I can
To accomplish this, I need some kind of subset of eBird data. The obs/geo/recent is the most inclusive query available. But it doesn't give any observer info. So if I want to keep tabs on other top birders in my area, I need integrate a whole bunch of queries. Which is undesirable for me and for eBird servers.
Also, in the interest of reduced latency and server load: it would be nice to have CSV or other format available to reduce fluff.