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:

http://ebird.org/ws1.1/data/obs/geo/recent?lng=-76.51&lat=42.46&dist=2&back=5&maxResults=500&locale=en_US&fmt=json

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

Unknown macro: {import}

28 Comments

  1. Anonymous

    is the 'dist' parameter the radius around the given lat/long?

    1. Paul Allen

      Yes, it is. Sorry for the confusion. I've updated the docs.

  2. Anonymous

    Is jsonp not provided?

    1. Paul Allen

      Sorry, not at this time.

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

    1. 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.

      1. 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.

        1. 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.

  4. 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..."?

    1. Jeff A. Gerbracht

      Your right, it returns species information which have been seen based on the "back" parameter.

  5. 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.

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

    2. Jeff A. Gerbracht

      Can you try this again, and let us know if you're now seeing data.
      Thanks

      1. 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

  6. 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.

    1. 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).)

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

    1. 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.

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

  9. Anonymous

    Could it ever be possible to request detail=full for this API?

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

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

    1. 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

    2. 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: 

      Unknown macro: {"comName"}

      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:

      Unknown macro: {"comName"}

      It seems like the record is removed, possibly having something to do with a nearby sighting on the same day?

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

  13. 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

    1. user-ad27b

      Please see https://confluence.cornell.edu/display/CLOISAPI/eBird-1.1-CacheInformation for information on update frequency.

  14. 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

    • figure out what to look for
    • figure where to go birding
    • keep tabs on my nemesis (nemeses)

    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.