eBird Web Services - Version 1.1
Data Source | Version | Status | Notes |
---|---|---|---|
eBird | 1.1 | deployed | enhances and supersedes v1.0 API |
NOTE: Please migrate to Version 2.0 of the APIs. These 1.1 APIs are no longer available
Endpoints
- ebird.org/ws1.1
This is the root of version 1.1. of eBird-specific web services.- ws1.1/data
This path contains data services.- ws1.1/data/obs/geo/recent
returns recent nearby observations - ws1.1/data/obs/geo_spp/recent
returns recent nearby observations of a species - ws1.1/data/obs/hotspot/recent
returns recent observations at hotspots - ws1.1/data/obs/hotspot_spp/recent
returns recent observations of a species at hotspots - ws1.1/data/obs/loc/recent
returns recent observations at locations - ws1.1/data/obs/loc_spp/recent
returns recent observations of a species at locations - ws1.1/data/obs/region/recent
returns recent observations in a region - ws1.1/data/obs/region_spp/recent
returns recent observations of a species in a region - ws1.1/data/notable/geo/recent
returns recent nearby notable observations - ws1.1/data/notable/hotspot/recent
returns recent notable observations at hotspots - ws1.1/data/notable/loc/recent
returns recent notable observations at locations - ws1.1/data/notable/region/recent
returns recent notable observations in a region - ws1.1/data/nearest/geo_spp/recent
returns nearest locations with observations of a species
- ws1.1/data/obs/geo/recent
- ws1.1/product
This path contains products consisting of aggregated raw data.- ws1.1/product/obs/hotspot/recent
This service provides a summary of recent sightings for birding hotspots.
- ws1.1/product/obs/hotspot/recent
- ws1.1/ref
This path contains supporting lookup services for the /data and /product services- ws1.1/ref/taxa
returns species in the ebird taxonomy - ws1.1/ref/hotspot/region
provides a list of eBird hotspots for a given region, optionally filtered to those with recent data - ws1.1/ref/hotspot/geo
provides a list of nearby eBird hotspots, optionally filtered to those with recent data - ws1.1/ref/location
returns location-based look-up data
- ws1.1/ref/taxa
- ebird.org/wstools1.1
This is location of gadget code and demo pages. - ebird.org/tools/google
This is location of original gadget code and demo pages.- ebird.org/tools/google/notable-birds.xml
This is location of gadget code for notable birds by state within the US. - ebird.org/tools/google/notable-birds-canada.xml
This is location of gadget code for notable birds by province/territory within the Canada
- ebird.org/tools/google/notable-birds.xml
- ebird.org/wsresource1.1
This is the root of the static resources that version 1.1 of the web services require. - wsresource1.1/images
- wsresource1.1/css
- wsresource1.1/js
- ws1.1/data
Making Sense of Endpoint URLs
There is a rational behind the URLs we use for endpoints. Find out what they mean.
30 Comments
Anonymous
Is there any way to get all sightings of a specific species at a given location, via the existing APIs? (It appears every API only provides the most recent sighting.)
Paul Allen
At this point we aren't ready to extend the API to allow retrieval of arbitrary data from the database. But, we'll keep your suggestion in mind. Thanks.
Anonymous
Ok, thanks. Guess I'll need to build a sightings front-end and export/import my stuff into eBird.
Interesting, since BirdsEye (iphone app) claims to show bird sightings within the last 3 years, using this API.
Paul Allen
Actually the Birds Eye folks are using a combination of this API and an entire download of the eBird data from the Avian Knowledge Network (accessible from here: http://www.avianknowledge.net/content/datasets/projects/ebird).
Anonymous
Holy cats ... wow. That's a lot of data.
No idea that was there. Thanks for the heads-up.
Anonymous
You can add this to your API want list, if it is not already there: I would like to be able to retrieve a list of all taxa at a locale (e.g., country or a state/province/political-unit-within-a-country) which ARE (one option) or ARE NOT (second option) on one of my lists (e.g, my World List or my US list). Thanks for considering this. Peter Bono (pbono@prba.com)
Anonymous
When you roll out new API calls (web service calls), do you roll them out one at a time (as you finish them) or do you roll them out in batches? For example, Jeff mentions that you are working on a "checklist" API call. Will that be available as soon as it is coded and tested internally, or will you wait until you decide to publish eBird-1.2?
Do you need "beta testers" for individual API calls or are we all "beta testers" all the time?
Thanks, Peter
Anonymous
Peter,
We generally roll out updated APIs in a batch but independent of eBird application functionality. We hoping to roll the checklist API calls out in the next month. Re the beta testing, I'll email you directly.
Thanks
Jeff
Anonymous
What is the status of the checklist API? Is this a read only API or read/write?
Anonymous
Any chance of getting a JSONP API in place? It's a drag having to proxy every API request.
Also, would be great to get a general update on what's going on with the API. Thanks!
user-ad27b
Hi All,
We've just enabled cross-origin resource sharing for all of the public eBird APIs. Given this, JSONP should not be necessary unless you need to support older browsers. To use JSONP, add a callback parameter to your JSON request. For example,
http://ebird.org/ws1.1/data/obs/region/recent?rtype=subnational1&r=US-NV&fmt=json&callback=parseArray
Hope this helps; please let us know if you have any comments or questions about these updates. Thanks!
Anonymous
Just tested this functionality out and it works as expected. Thanks for the quick response!
Anonymous
Is there an easy way to see how many checklists a hotspot has? As a hotspot editor I can go in and look one by one, but there are 900+ in my state, and I was looking for something more efficient, like a csv file I could just download.
As for why, well, I'm just curious - what are the most birded spots in my state? But also I occasionally have to merge them, or ask to have them reverted to personal spots, and it would be helpful information.
thanks!
Andrew Core
AZ
Disabled Account Randy Robinson
I believe there is a bug in "recent nearby observations" (ws1.1/data/obs/geo/recent) and "recent observations at hotspots" (ws1.1/data/obs/hotspot/recent).
This is easiest to see with hotspots. When I ask for recent sightings (detail=full) at a hotspot that has more than one checklist for the time period, the first checklist that comes back is complete. However, the following checklists all appear incomplete. I check this using the sub-id to look at the checklist on ebird.org.
This is harder to check with nearby observations because that api does not support detail=full. However, if you use nearby observations on a hotspot location you can see the same checklists in both results. The behavior is similar for each - checklists after the first one are incomplete.
My application is here: http://birdingwashington.info/dashboard/
You can see the behavior: 1) select a state, 2) choose "hotspots", 3) click on a hotspot, 4) if there are multiple checklists click on the "eBird chklst" buttons to see the checklists at ebird.org. At the very bottom of the page, the line under the map, you can see the api url I am using.
Let me know if you can't replicate this or if I am misunderstanding how the api works.
Thanks,
Randy Robinson
Seattle, WA
user-ad27b
Hi Randy,
It's a bit confusing because obs/hotspot/recent doesn't return ALL observations at that hotspot, only the MOST RECENT sighting of each bird. So you'll always see every bird on the latest checklist but earlier checklists will tend to only show rarer birds that weren't detected on later visits. Hope this helps.
Anonymous
One useful API to have is to return the date the species list was last changed. That way, apps can see if their local copy of species list is up to date without having to download the whole list. Otherwise the options are to either manually update your app / webpage when the species list changes or to periodically download the entire list, parse the XML and update the list eventhough the list will change only once a year.
Anonymous
This query returns Barnacle Goose on 12/28/12 (yesterday):
http://ebird.org/ws1.1/data/notable/geo/recent?lng=-73.89&lat=40.89&dist=2&back=5&maxResults=500&detail=simple&locale=en_US&fmt=xml
However, this query does not return Barnacle Goose (5 days back):
http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-73.89&lat=40.89&sci=branta%20leucopsis&dist=20&back=5&maxResults=500&locale=en_US&fmt=xml
This query returns Barnacle Goose on 12/05/12:
http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-73.89&lat=40.89&sci=branta%20leucopsis&dist=20&back=30&maxResults=500&locale=en_US&fmt=xml
Any idea why the most recent sitings for Barnacle Goose at 40.89311,-73.89412 are filtered from results?
A query for Canada Goose at 40.89311,-73.89412 will return many recent checklists that also include Barnacle Goose, however a specific query for Barnacle Goose will not yield the most recent sightings.
Jeff A. Gerbracht
These API calls return different results by default,
The notable/geo/recent API by default returns provisional records as well as vetted records, where the obs/geo_spp/recent only returns vetted records. You can include the query parameter, &includeProvisional=true with the obs/geo_spp/recent call to return both provisional and vetted records.
http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-73.89&lat=40.89&sci=branta%20leucopsis&dist=20&back=5&maxResults=500&locale=en_US&fmt=xml&includeProvisional=true
Anonymous
What's the status of the subnational2 lookup?
https://confluence.cornell.edu/display/CLOISAPI/AKN-1.0-Subnational2
Will this be available soon?
Thanks,
Tom Auer
Anonymous
Is the checklist API available now, or if not when might it become available? Jeff mentioned in his post of April 27, 2011 that it might be coming soon, but I haven't been able to find documentation for it.
Thanks,
Harold Mills
Jeff A. Gerbracht
Changes in both resources and in development directions have caused us to put releasing the checklist API on hold. I would be very interested in hearing how different developers would use a checklist API, especially since the great ideas you come up with help us make those tough prioritization decisions.
Thanks
Jeff
Anonymous
Hi Jeff,
Thanks for the update on the checklist API. I'd be interested in using checklists to limit the species displayed in a smartphone app according to location and time of year.
Harold
Anonymous
I had been "wget"ing or "cURL"ing my way into the API to grab the XML then parse it to make appropriate KML files out of it for display in Google Maps and Google Earth. At some point it has become "Forbidden" for me to access the API URLs via that method. Any word on how to fix this problem. I can get to the URLs via a browser window without a problem, but it causes problems when I try any of the API calls I was making via a wget or curl.
Bryan
Anonymous
Is there anyway to get my submissions, using the api?
Anonymous
It doesn't appear so. But I agree, that would be really useful!
- Ben
Anonymous
Would be nice to have a fully open api, where we could develop prototypes that could possibly be brought into ebird.
Anonymous
What's the status on a submission API? I'm out every day, currently using Notes on my iPhone to record banding codes, but I know I could do much better in designing my own app (I'm an app developer). I've tried BirdLog but it's terribly impractical for in-the-field recording (takes forever to record anything, Notes is much better). The problem, of course, is that finding the time to turn my notes into checklists is tough so I end up having to spend an hour or two doing this manually (so monotonous!) every couple weeks, and if I could do it in the field I'd probably be more open to reporting incidentals more often, and maybe encourage others to do the same.
Anonymous
Howdy all, I just released the following website, intended for public usage:
http://birdsearch.org
It makes use of the following API calls:
There's OODLES more functionality I'd like to add, so I'll keep watching these pages for any improvements to the API.... :)
Oh, and the code is all open source and found on github here: https://github.com/benkeen/birdsearch.org
If anyone wants to reach me, feel free to email at ben.keen@gmail.com.
Enjoy!
- Ben
Anonymous
Hi All,
We are releasing a bird sighting and journal platform for south Africa. Does anyone know when we can get an API that allows us to pull in species photos, bird sounds and bird information?
Appreciate any help on this.
Jean
Disabled Account Randy Robinson
Recent notable sightings in a region seems to have become flaky in the last couple of days. When "detail=full" is specified, sometimes only the simple field results are returned. For example:
http://ebird.org/ws1.1/data/notable/region/recent?rtype=subnational1&r=US-AZ&detail=full&fmt=xml&back=14
returned the following:
<response><header><locale country="US" language="en"/><timestamp>2014-01-24T20:34:01.480-05:00</timestamp><criteria><fmt>xml</fmt><hotspot>false</hotspot><rtype>subnational1</rtype><r>US-AZ</r><back>14</back><max-results>10000</max-results><detail>full</detail></criteria></header>
<result>
<sighting><loc-id>L1075433</loc-id><location-private>true</location-private><obs-dt>2014-01-24 16:45</obs-dt><obs-reviewed>false</obs-reviewed><obs-valid>false</obs-valid><loc-name>Salero Ranch Unit 1 Lot 10 yard</loc-name><how-many>1</how-many><lat>31.6094605</lat><lng>-110.9072828</lng><com-name>Costa's Hummingbird</com-name><sci-name>Calypte costae</sci-name></sighting>
This is followed by the rest of the sightings, all of which have only the simple field results.
At other times, the same request will return full field results.
Am I missing something or is there a problem with the returned results?
The app where this occurs is here: http://birdingwashington.info/dashboard/
Thanks,
Randy Robinson