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 |
Format
Result Formats
Currently, two result formats are supported: xml and jsonGeneral result notes for each currently supported format, including special conditions and error handling.
JSON
...
Simple Detail JSON Example Result
No Format |
---|
[{"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 Example result for full detail. The "full" detail nearly triples the size of the response on average:.
No Format |
---|
[{"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:
No Format |
---|
["Latitude out of range","Longitude out of range"] |
No Format |
---|
[ {"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
No Format |
---|
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} |