Description

Returns the most recent sighting date and specific location for the requested species of bird reported within the number of days specified by the "back" parameter and reported in a given area.

 This is part of the eBird version 1.1 API.

URL

Base URL

http://ebird.org/ws1.1/data/obs/geo_spp/recent

Examples

Minimal:

http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-76.51&lat=42.46&sci=branta%20canadensis

Fully specified:

http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-76.51&lat=42.46&sci=branta%20canadensis&dist=2&back=5&maxResults=500&locale=en_US&fmt=json&includeProvisional=true

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

sci

yes

 

any scientific name

larus%20delawarensis

scientific name of the species of interest (not case sensitive).  This only accepts scientific names of the category "species" and will generate an "unknown species" error for names in any other category.  See eBird-1.1-SpeciesReference for a list of supported scientific names and a complete list of categories.

 

hotspot

 

false

true,false

false

set to true if results should be limited to sightings at hotspots

 

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"
}]

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}
  • No labels

7 Comments

  1. Anonymous

    The URL

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

    does not return just Brants. Is this an error? My guess is that geo should be geo-spp ??

    Tom Wetmore

  2. user-ad27b

    Right, thanks. I've fixed it.

  3. Anonymous

    Sorry, meant Canada Goose instead of Brant, and geo_spp instead of geo-spp.

    Tom Wetmore

  4. Anonymous

    I send the request to server

    http://ebird.org/ws1.1/data/notable/geo/recent?back=30&lng=-122.382600&lat=37.731200&dist=50http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-76.51&lat=42.46&sci=branta%20canadensis
    which returns a list of notable birds with the loc-id=L235030.
    Then I send the reques http://ebird.org/ws1.1/data/notable/hotspot/recent?r=L235030 or http://ebird.org/ws1.1/data/notable/loc/recent?r=L235030
    But responces contains an empty list of observations for this location though should return at least one observation.

    1. Anonymous

      First URL is

      http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-76.51&lat=42.46&sci=branta%20canadensis

      It's example from this page.

  5. Anonymous

    Hello.

    I experience troubles with this request with response time. If I use the one from examlple - it's fine - response is 1second or so:

    http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-76.51&lat=42.46&sci=branta%20canadensis

    But if I add value with distance - response time becomes 16 seconds or so. Second time when I request the same thing response becomes 1 second.

    http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-76.51&lat=42.46&sci=branta%20canadensis&dist=50&nbsp;

    At first I thought it's because I've put larger radius. However I've tried to set dist=1 and got the same response time. 

    http://ebird.org/ws1.1/data/obs/geo_spp/recent?lng=-76.51&lat=42.46&sci=branta%20canadensis&dist=1

    The same behavior if I add includeProvisional=true value.

    Can this be solved somehow? 

    1. Jeff A. Gerbracht

      Getting values with distance are something that we can't warehouse so response time will be dependent on the database and which portions of the eBird dataset are currently in cache.

         Jeff