| Panel | |
|---|---|
|
Notable eBird Sightings Web Service API and Gadget
| Panel | |
|---|---|
|
Gadget
API
URL | description | status | notes |
|---|---|---|---|
http://ebird.org/ws1.0/data/notable/recent?subnational1Code=US-PA&subnational1Code=US-NY | returns notable sightings for the given state(s) | deployed |
|
http://ebird/byloc.org/ws1.0/data/notable/recent?locIDs=L97555,L259855countryCode=US&countryCode=CA | returns notable sightings for the given country(ies Return summary of recent sightings at the given locID(s) | deployed |
|
Parameter Descriptions
parameter | required | default | value options | example value | description | status | locIDs | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
subnational1Code | either subnational1Code or countryCode is required yes | n/a | Valid subnational codes are available from AKN-1.0-Subnational1 | US-PA | There is no limit to the number of subnational1Codes that can be provided in one request. However, subnational1Code and countryCode parameters cannot be provided in the same request. If both are provided, the subnational1Code parameters are ignored. | deployed | |||||||
countryCode | either subnational1Code or countryCode is required | n/a | Valid country codes are available from AKN-1.0-Country | US | There is no limit to the number of countryCodes that can be provided in one request. However, subnational1Code and countryCode parameters cannot be provided in the same request. If both are provided, the subnational1Code parameters are ignored | comma-separated list of up to three locIDs | L97555,L259855 | The data summary is computed using data submitted to the given locIDs (up to three). | deployed | ||||
locale | no | en_US | Java standard locale codes | en_US | Language/locale of common names to be provided in the response (when translations are available) | implemented, not deployed (as of June 27, 2008) | daysBack | no | 0 | 0, 1, 2, 3, 4, 5, 6, 7 | 7 | . This also specifies the language used in the description of the sighting. How many days backwards to look in computing the summary. Zero means use observations submitted for today. One means use observations for today and yesterday. Etc. | deployed |
Result Caching
Results are cached on the server for 30 minutes, so repeated calls to the same URL will usually result in exacted exactely the same response. The time that the response was actually computed is provided in the header time stamp.
XML Result Format
| No Format |
|---|
<?xml version="1.0" encoding="UTF-8"?> <response> - <header> <locale country="US" language="en"/> <timestamp>2008-0607-27T1511T14:5759:5800.877659-04:00</timestamp> - <criteria> <property id="locIDsubnational11Code" value="L97555US-NY" description="SapsuckerNew WoodsYork"/> <property id="daysBacksubnational11Code" value="7US-PA" description="Pennsylvania"/> </criteria> <comment/> </header> - <result> - <notable-sighting> <sub-id>S3985178</sub-id> <obs-id>OBS55408334</obs-id> <checklist-id>CL21788</checklist-id> - <description> 1 White-crowned Sparrow was observed at Sapsucker Woods in Tompkins County, New York, US on 9 July by CLO Kiosk. <result></description> <sighting> <obs-dt>2008-07-09</obs-dt> <species-id>cangoo<id>whcspa</species-id> <scientific-name>Brantaname>Zonotrichia canadensis<leucophrys</scientific-name> <common-name>Canadaname>White-crowned Goose<Sparrow</common-name> <loc-id>L97555</loc-id> <location private="false">Sapsucker Woods</location> <longitude>-76.4513778</longitude> <latitude>42.4791969</latitude> <observer>CLO Kiosk</observer> <how-many>20<many>1</how-many> <presence-noted>false</presence-noted> <obs-reviewed>false</obs-reviewed> <obs-valid>false</obs-valid> <num-checklists>2</num-checklists>observers>5</num-observers> <subnational2-code>US-NY-109</subnational2-code> <subnational2-name>Tompkins</subnational2-name> <subnational1-code>US-NY</subnational1-code> <subnational1-name>New York</subnational1-name> <country-code>US</country-code> <country-name>United States</country-name> </notable-sighting> - <notable-sighting> <sub-id>S3983932</sub-id> <obs-dt>2008-06-27</obs-dt> id>OBS55398293</obs-id> <checklist-id>CL22361</checklist-id> - <description> 1 Greater Scaup was observed at Jamaica Bay Wildlife Refuge in Queens County, New York, US on 8 July by Doug Gochfeld. </sighting>description> <sighting> <obs-dt>2008-07-08</obs-dt> <species-id>norbob<id>gresca</species-id> <scientific-name>Colinusname>Aythya virginianus<marila</scientific-name> <common-name>Northernname>Greater Bobwhite<Scaup</common-name> <loc-id>L165143</loc-id> <location private="false">Jamaica Bay Wildlife Refuge</location> <longitude>-73.82697</longitude> <latitude>40.62044</latitude> <observer>Doug Gochfeld</observer> <how-many>1</how-many> <presence-noted>false</presence-noted> <num-checklists>1</num-checklists><obs-reviewed>true</obs-reviewed> <obs-valid>true</obs-valid> <num-observers>2</num-observers> <subnational2-code>US-NY-081</subnational2-code> <subnational2-name>Queens</subnational2-name> <subnational1-code>US-NY</subnational1-code> <obs-dt>2008-06-25</obs-dt><subnational1-name>New York</subnational1-name> <country-code>US</country-code> </sighting> <country-name>United States</country-name> </notable-sighting> - </result> </response> |
Potential Enhancements
...
- add observer name to data and display
Enhancements for eTT gadget/data
- Link to AAB species instead of eBird reports
- link to map showing location of sighting (using kiosk map)
- Identfiy rarities and specialties
- Multiple time frames (week, month); for these, show date last observed
- Support multiple points (via polygon)
Enhancements targeted for sprint
...
- Must regurgitate parameter in response header.
- Validation check parameter values.
- Default value is 1, which indicates a time period of midnight of the previous day to "now".
- E.g., "3" would indicate midnight 3 days ago to "now". Thus the report always covers 3 x 24 hours + however far through the day we are right now.
| Wiki Markup |
|---|
{import:eBird-footer} |
...