Results and Error Conditions
Result Field Descriptions
Simple Detail Fields
These core fields are included for all detail levels (simple and full).
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 |
Full Detail Fields
These fields are included only when full detail is requested.
Field |
Description |
|---|---|
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 |
Result Formats
Currently, two result formats are supported: xml and json.
JSON
Simple Detail JSON Example Result
[{"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"}]
Full Detail JSON Example Result
Note that "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"}]
Example JSON Error Response
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"]
[ {"errorCode": "xxx.yy.zzz.",
"errorMsg":"Latitude out of range"}
]
XML
Simple Detail XML Example Result
Full Detail XML Example Result
Example XML Error Response
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).
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.
CONVERT THIS TO A TABLE
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}