You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 55 Next »

Description

Returns recent sightings of a species in a region

 This is part of the eBird version 1.1 API.

URL

Base URL

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

Examples

Minimal:

http://ebird.org/ws1.1/data/obs/region_spp/recent?rtype=subnational1&r=US-NV&sci=larus%20delawarensis

Fully specified:

http://ebird.org/ws1.1/data/obs/region_spp/recent?rtype=subnational1&r=US-NV&sci=larus%20delawarensis&back=5&maxResults=500&locale=en_US&fmt=json&includeProvisional=true

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

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).  See eBird-1.1-SpeciesReference for a complete list of supported scientific names

 

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