Fields in green are included in the results only if the input parameter detail=simple (default). If detail=full then all result fields will be included.
Field |
Description |
commonName |
species common name. not included in the 'simple' detail if a scientific name was specified as an input parameter |
scientificName |
species scientific name. not included in the 'simple' detail if a scientific name was specified as an input parameter |
obsDt |
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 |
The number observed. Not included if only presence was noted |
locID |
unique identifier for the location |
locName |
location name |
lat |
latitude of the location |
lng |
longitude of the location |
subnational2Code |
county code |
subnational2Name |
county name |
subnational1Code |
state/province ISO code |
subnational1Name |
state/province name |
countryCode |
country ISO code |
countryName |
country name |
firstName |
observer's first name |
lastName |
observer's last name |
subID |
submission ID |
obsID |
observation ID |
checklistID |
checklist ID |
obsReviewed |
'true' if obs has been reviewed. 'false' otherwise |
obsValid |
'true' if obs has been deemed valid by a regional reviewer. 'false' otherwise |
locationPersonal |
'true' if location has been marked private by the owner. 'false' otherwise |
presenceNoted |
'true' if user marked presence but did not count the number of birds. 'false' otherwise |
Format
General result notes for each currently supported format, including special conditions and error handling.
JSON
Example result for simple detail:
[{"howMany":"39", "lat":42.4791969, "locID":"L97555", "locName":"Sapsucker Woods", "commonName":"Mallard", "lng":-76.4513778, "scientificName":"Anas platyrhynchos", "obsDt":"2009-03-09 11:30"}, {"lat":42.4791969,"locID":"L97555","locName":"Sapsucker Woods","commonName":"Mourning Dove","lng":-76.4513778,"scientificName":"Zenaida macroura","obsDt":"2009-03-09 11:30"}]
Example result for full detail. The "full" detail nearly triples the size of the response on average:
[{"lat":42.446935, "obsValid":true, "firstName":"Marshall", "locID":"L212389", "obsID":"OBS65284875", "subID":"S4684058", "obsReviewed":true, "presenceNoted":false, "commonName":"Herring x Lesser Black-backed Gull (hybrid)", "scientificName":"Larus argentatus x fuscus", "obsDt":"2009-03-09", "howMany":1, "locationPrivate":false, "subnational2Code":"US-NY-109", "subnational1Code":"US-NY", "locName":"Game Farm and Compost Pile", "subnational2Name":"Tompkins", "subnational1Name":"New York", "lng":-76.4375442, "countryCode":"US", "countryName":"United States", "checklistID":"CL22224", "lastName":"Iliff"},{"lat":42.4676667,"obsValid":true,"firstName":"Tom","locID":"L583112","obsID":"OBS65588657","subID":"S4705440","obsReviewed":false,"presenceNoted":false,"commonName":"Great Horned Owl","scientificName":"Bubo virginianus","obsDt":"2009-03-09 11:30","howMany":1,"locationPrivate":false,"subnational2Code":"US-NY-109","subnational1Code":"US-NY","locName":"Schulenberg home","subnational2Name":"","subnational1Name":"","lng":-76.4511389,"countryCode":"US","countryName":"United States","checklistID":"CL22224","lastName":"Schulenberg"}]
Special Conditions & Error Handling
If there are validation problems with the input parameters the response will be an HTTP 400 error code that includes a simple array containing details of the problems encountered:
["Latitude out of range","Longitude out of range"]
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 = One or more locIDs are required error.data.rtype_required = The parameter 'rtype' 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.unknown_species = Unknown species: {0}