...
Result Field Descriptions
Simple Detail Fields
These core fields are included for all detail levels (simple and full).
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 |
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 a regional reviewer. 'false' otherwise |
Full Detail Fields
These fields are included only when full detail is requested (supported services only).
...
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
...
countryName
...
country-name
...
country name
...
firstName
...
first-name
...
observer's first name
...
lastName
...
last-name
...
observer's last name
...
subID
...
sub-id
...
submission ID
...
obsID
...
obs-id
...
observation ID
...
checklistID
...
checklist-id
...
checklist ID
...
locationPersonal
...
location-personal
...
'true' if location has been marked private by the owner. 'false' otherwise
...
presenceNoted
...
presence-noted
...
| Include Page | ||||
|---|---|---|---|---|
|
| Include Page | ||||
|---|---|---|---|---|
|
...
Result Formats
Currently, two result formats are supported: xml and json.
...
XML
...
Example XML Error Response
| No Format |
|---|
[{"howMany":"39",
"lat":42.4791969,
"locID":"L97555",
"locName":"Sapsucker Woods",
"comName":"Mallard",
"lng":-76.4513778,
"sciName":"Anas platyrhynchos",
"obsDt":"2009-03-09 11:30"},
{"lat":42.4791969,"locID":"L97555","locName":"Sapsucker Woods","comName":"Mourning Dove","lng":-76.4513778,"sciName":"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.
| No Format |
|---|
[{"lat":42.446935,
"obsValid":true,
"firstName":"Marshall",
"locID":"L212389",
"obsID":"OBS65284875",
"subID":"S4684058",
"obsReviewed":true,
"presenceNoted":false,
"comName":"Herring x Lesser Black-backed Gull (hybrid)",
"sciName":"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,"comName":"Great Horned Owl","sciName":"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
<response><header><locale country="" language="en"/><timestamp>2009-05-15T15:40:30.031-04:00</timestamp><criteria><command><fmt>xml</fmt><include-provisional>false</include-provisional><hotspot>true</hotspot><rtype>loc</rtype><back>14</back><max-results>10000</max-results><detail>simple</detail></command></criteria><errors><error><error-msg>Please specify a region code</error-msg><error-code>error.data.rcodes_required</error-code></error></errors></header><result/></response>
|
JSON
Example JSON Error Response
The If there are validation problems with the input parameters the response will be an HTTP 400 error code that includes , detailing the problems encountered in a simple JSON array containing details of the problems encountered:
| No Format |
|---|
[{"errorMsg":"Latitude out of range",
"errorCode":"error.data.lat_out_of_range"},
{"errorMsg":"Longitude out of range",
"errorCode":"error.data.lng_out_of_range"}]
|
XML
Simple Detail XML Example Result
| No Format |
|---|
<?xml version="1.0" encoding="UTF-8"?>
<response><header><locale country="" language="en"/><timestamp>2009-05-15T15:37:38.625-04:00</timestamp><criteria><command><fmt>xml</fmt><include-provisional>false</include-provisional><hotspot>true</hotspot><rtype>loc</rtype><r>L99381</r><back>14</back><max-results>10000</max-results><detail>simple</detail></command></criteria></header><result><sighting><loc-id>L99381</loc-id><obs-dt>2009-05-15 06:05</obs-dt><obs-reviewed>false</obs-reviewed><obs-valid>true</obs-valid><loc-name>Stewart Park</loc-name><how-many>0</how-many><lat>42.4613266</lat><lng>-76.5059255</lng><com-name>American Crow</com-name><sci-name>Corvus brachyrhynchos</sci-name></sighting><sighting><loc-id>L99381</loc-id><obs-dt>2009-05-15 06:05</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>American Goldfinch</com-name><sci-name>Carduelis tristis</sci-name></sighting><sighting><loc-id>L99381</loc-id><obs-dt>2009-05-15 06:05</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>American Redstart</com-name><sci-name>Setophaga ruticilla</sci-name></sighting></result></response>
|
Full Detail XML Example Result
| No Format |
|---|
<?xml version="1.0" encoding="UTF-8"?>
<response><header><locale country="" language="en"/><timestamp>2009-05-15T15:38:46.390-04:00</timestamp><criteria><command><fmt>xml</fmt><include-provisional>false</include-provisional><hotspot>true</hotspot><rtype>loc</rtype><r>L99381</r><back>14</back><max-results>10000</max-results><detail>full</detail></command></criteria></header><result><sighting><sub-id>S4974341</sub-id><obs-id>OBS70100264</obs-id><checklist-id>CL22224</checklist-id><loc-id>L99381</loc-id><presence-noted>false</presence-noted><country-name>United States</country-name><country-code>US</country-code><subnational2-name>Tompkins</subnational2-name><subnational2-code>US-NY-109</subnational2-code><first-name>Brad</first-name><subnational1-name>New York</subnational1-name><last-name>Walker</last-name><subnational1-code>US-NY</subnational1-code><obs-dt>2009-05-15 06:05</obs-dt><obs-reviewed>false</obs-reviewed><obs-valid>true</obs-valid><loc-name>Stewart Park</loc-name><how-many>0</how-many><lat>42.4613266</lat><lng>-76.5059255</lng><com-name>American Crow</com-name><sci-name>Corvus brachyrhynchos</sci-name></sighting><sighting><sub-id>S4974341</sub-id><obs-id>OBS70100271</obs-id><checklist-id>CL22224</checklist-id><loc-id>L99381</loc-id><presence-noted>false</presence-noted><country-name>United States</country-name><country-code>US</country-code><subnational2-name>Tompkins</subnational2-name><subnational2-code>US-NY-109</subnational2-code><first-name>Brad</first-name><subnational1-name>New York</subnational1-name><last-name>Walker</last-name><subnational1-code>US-NY</subnational1-code><obs-dt>2009-05-15 06:05</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>American Goldfinch</com-name><sci-name>Carduelis tristis</sci-name></sighting></result></response>
|
Example XML Error Response
<response><header><locale country="" language="en"/><timestamp>2009-05-15T15:40:30.031-04:00</timestamp><criteria><command><fmt>xml</fmt><include-provisional>false</include-provisional><hotspot>true</hotspot><rtype>loc</rtype><back>14</back><max-results>10000</max-results><detail>simple</detail></command></criteria><errors><error><error-msg>Please specify a region code</error-msg><error-code>error.data.rcodes_required</error-code></error></errors></header><result/></response>
|
Special Conditions and Error Handling
...
| 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 = 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.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.
|