Description

Returns all recent observations of notable bird species in a given area.

 This is part of the eBird version 1.1 API.

URL

Base URL

http://ebird.org/ws1.1/data/notable/region/recent

Examples

Minimal:

http://ebird.org/ws1.1/data/notable/region/recent?rtype=subnational1&r=US-NV

Fully specified:

http://ebird.org/ws1.1/data/notable/region/recent?rtype=subnational1&r=US-NV&back=5&maxResults=500&locale=en_US&fmt=json

Parameter Descriptions

Parameter Name

Required

Default

Value Options

Example Value

Description

rtype


auto-determined from 'r' parameter

country,subnational1,subnational2

subnational1

the region type you are interested in.

r

yes

 


 

region code corresponding to selected region type. see region code reference

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.  currently, only the 'simple' format is supported for this service.  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

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

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

3 Comments

  1. Anonymous

    Is there any chance we can start getting the "details/comments" section back with this result set? (ie. photo links, etc.)

  2. Anonymous

    I'm having trouble finding out how, exactly, notable sightings are defined: are sightings flagged as "notable" automatically based on the probability that a sighting would be made in this given place, at this time, in this quantity, based on previously reported observations? If so, would it be possible to make this metric available so that one could order or label recent notable sightings based on their "notability"? This would prove more accurate and useful than using ABA codes which are spatially and temporally indiscriminate (ie, a Townsend's Warbler is certainly a rarity in eastern Massachusetts in winter, far more than one would imagine from its ABA code 1 designation).

    1. Jeff A. Gerbracht

      eBird records are compared with regional "filters" which define whether a species and count are unexpected for that region and time of year.    The API considers a species "notable" if any count for that species would be unexpected.      It is both spatially and temporally based so in that way, it's much better than simply using the ABA code designations.   However, within a region/time period, there is no way to further rank the species,  they are either notable or not.

         Jeff