eBird Hot Spot List - Version 1.0
Summary
Get a list of eBird hotspots, for a state or for a country. The eBird Hot Spots Examples page contains links for this API for each state and province in the US and Canada.
API
URI |
description |
status |
notes |
---|---|---|---|
ws1.0/data/hotspot/list?countryCode=<2-letter ISO country code> |
Return list of hotspots found in the given country |
coded and deployed |
|
ws1.0/data/hotspot/list?subnational1Code=<subnational1 code> |
Return list of hotspots names found in the given "state" |
coded and deployed |
|
parameter |
required |
default |
value options |
description |
status |
---|---|---|---|---|---|
countryCode |
one of countryCode or subnational1Code is required |
n/a |
|
see AKN-1.0-Country |
coded and deployed |
subnational1Code |
one of countryCode or subnational1Code is required |
n/a |
|
coded and deployed |
|
format |
no |
csv |
csv, xml |
format to use for response; this parameter is case sensitive |
coded and deployed |
Test URLS
Caching
Responses to this API are cached up to 24 hours hours on our servers. Because of this, API consumers might see inconsistencies between various calls submitted at the same time (e.g. a particular US-VA hot spot is included in the response to a request for all the US-VA hot spots, but it is not included in a request submitted at the same time listing all the US hot spots). In the XML response format, the time stamp in the header section shows the time that the response was originally created, and so API consumers can see the age of the particular response.
CSV Result Format
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"
<loc ID>, <country code>, <subnational1 code>, <latitude>, <longitude>, "<name>"
Example
L453718, US, US-RI, 41.3302, -71.8375, "Avondale Farm"
L231740, US, US-RI, 41.4496915, -71.3987547, "Beavertail State Park"
L466297, US, US-RI, 41.3202, -71.8303, "Big Maschaug Pond, Watch Hill"
L490189, US, US-RI, 41.3623801, -71.4880371, "Camp Cronin"
L487743, US, US-RI, 41.8591418, -71.3376617, "Central Pond Reservoir"
L466303, US, US-RI, 41.3571, -71.6374, "Charlestown Breachway"
L166174, US, US-RI, 41.49133, -71.292656, "Easton Pond"
L487669, US, US-RI, 41.7074586, -71.6359663, "Flat River Reservoir"
L357306, US, US-RI, 41.9668934, -71.5573883, "Fort Refuge"
L384479, US, US-RI, 41.4743419, -71.3398933, "Ft. Adams State Park"
XML Result Format
Example
<?xml version="1.0" encoding="UTF-8"?> <response> <header> <locale country="US" language="en"/> <timestamp>2008-07-25T10:54:16.432-04:00</timestamp> <criteria> <property id="subnational11Code" value="US-RI" description="Rhode Island"/> </criteria> <comment/> </header> <result> <hotspot> <loc-id>L453718</loc-id> <location>Avondale Farm</location> <longitude>-71.8375</longitude> <latitude>41.3302</latitude> <subnational1-code>US-RI</subnational1-code> <country-code>US</country-code> </hotspot> <hotspot> <loc-id>L231740</loc-id> <location>Beavertail State Park</location> <longitude>-71.3987547</longitude> <latitude>41.4496915</latitude> <subnational1-code>US-RI</subnational1-code> <country-code>US</country-code> </hotspot> </result> </response>
Potential Improvements
- Add summary info to each record:
- # of checklists per hotspot
- Add KML format option to produce GoogleEarth/Map compatible files.
12 Comments
Christopher Wood
This is really great. One thing that would be particularly useful is if we could have the number of checklists per hotspots. This gives some indication of how "good" they are, how much use their is and if we should be combine hotspots. I've attached a file, which I use to make a KML file using GPS Visualizer. I also attached the hotspot file that I get from there.
Anonymous
Chris-
nice upt-todate way to access hotspots.
I agree though with your suggested improvement. Can we have the number of lists at each hotspot added as text to the hotspot decription?
We go this information when we got an e-mail from Cornell listing the hotspots (pre-October 2008)
John Berner
Houston
Anonymous
It would be terrific to have a web service that returns hotspots within a given radius of a user-provided latitude and longitude.
Anonymous
It's not pretty but this will give you the great circle distance in miles between two lat long in the northern hemisphere.
=1.15077945*2*ASIN(SQRT((SIN((Lat1*(PI()/180)-Lat2*(PI()/180))/2))^2+COS(Lat1*(PI()/180))COS(Lat2(PI()/180))(SIN((ABS(Long1)(PI()/180)-ABS(Long2)*(PI()/180))/2)^2)))*180*60/PI()
Alan Bragg
Anonymous
It would be handy if we could query hotspots by date as well not just location.
Gerco
Anonymous
If you're interested in loading eBird hotspots to your Garmin GPS as Custom Points of Interest (POI), do the following:
Save a hotspot CSV file from eBird to your hard disk;
Open the file up in Excel;
Delete the first three columns (<loc ID>, <country code>, <subnational1 code>);
Move the longitude to the first column;
Set the format of the longitude and latitude column to 'numbers', five (5) digits past the decimal;
Delete all quotation marks;
Save the file in CSV (comma delimited format);
Use the free Garmin Custom POI loader software to load the file on to an SD card, or directly to the GPS.
There may be another or simpler way, but this worked for me on a Nuvi 750. You can always delete some not so hot hotspots while you're in Excel.
I now have about 1000 Florida hotspots in my GPS. I've been waiting to do this for a long time. Thank you
Now I'm waiting to get a GPX file that loads into MapSource, since I prefer to plan my trips on my computer. Changing the XML extension to GPX won't work. I read that there are some issues having to do with elevation tags.
Anonymous
I found that some hotspots use seven columns. One of the hotspots in Maine is "Black Cove, Portland". "Black Cove" is in Column six/F, and "Portland" is in column seven/G. If you delete the quotation marks, I don't think you'll retain "Portland". Therefore, I've modified my instructions slightly. I now recommend that you leave in the quotation marks. Otherwise you will not get the seventh column after the conversion. Below are my revised instructions, and a macro for Excel that automatically formats the downloaded CVS file from eBird to a format that can be converted to GPX format for MapSource. You should be able to copy and paste it, as is. Since posting the original message, I've discovered a shareware program called PoiEdit, which works well at converting the edited CVS file to a GPX file. I also recommend that you read Alan Bragg's message of Dec 14 for other options. - Wil Domke, Miami, FL
q Download a Hotspot CVS file from eBird
q Open the file in Excel
q Delete the first three columns
q Move the Longitude column to column 1
q Change the format of the Longitude and Latitude columns (columns 1 & 2) to a number format, with five (5) digits past the decimal
q Save the file as a CSV file
q Use PoiEdit (http://www.poiedit.com shareware software) to open the file
q Safe the file as GPX format
Use Custom POI Loader to load the file to your Garmin or SD card. You can also open the file in MapSource and make edits before using POI to load to you card or device.
Use the Macro below to automatically delete columns and format the downloaded eBird CVS file, or record your own.
Sub eBirdConv()
'
' eBirdConv Macro
' Macro recorded 11/26/2008 by
'
'
Columns("A:C").Select
Selection.Delete Shift:=xlToLeft
Columns("B:B").Select
Selection.Cut
Columns("A:A").Select
Selection.Insert Shift:=xlToRight
Columns("A:B").Select
Selection.NumberFormat = "0.00000"
End Sub
Marshall J. Iliff
If anyone else has developed instructions for how to do this with other GPS models please post them here and drop us an email at ebird@cornell.edu. We'd like to expose this hotspot file and provide instructions to users on how to load it to their GPS.
Thanks!
Anonymous
You can convert your csv file to gpx which can be read by Mapsource at http://www.gpsvisualizer.com/convert_input
add a header row with name, description, latitude and longitude
remove quotes around hotspot name
organize the data in 4 corresponding columns ebird L number, site name, Latitude, Longitude
The Hot Spot number will appear as your waypoint name (It's a lot shorter than the description and it's unique) the description will appear in the "comment" field.
Check my web site for gpx files you can download for birding locations. I have ones that correspond to the Great Florida Birdin g Trail. See my site http://birdingtrails.googlepages.com/
Alan Bragg
Bedford MA
Anonymous
I haven't tried your method, but I don't see any reason why it wouldn't work. I do prefer to use the complete name for the waypoint name. I tried the shortened waypoint names a while back, and found that I had too much trouble finding locations. I had to carry trail guides to help me decode my waypoint codes. The newer GPS', like the Garmin Nuvi 750 work very well with long waypoint names. Your recommendation is almost essential for older GPS', like the Garmin GPSMAP 60C, and maybe other handhelds, which limit the number of characters for waypoints. - Wil Domke, Miami, FL
Anonymous
I'm getting an error when I attempt to download the list of hotspots in Colorado:
http://ebird.org/ws1.0/data/hotspot/list?subnational1Code=US-CO&format=xml
gives me the error:
error on line 2 at column 55210: Encoding error
The error is in the hotspot record following Sego Springs SWA. Here's the offending xml:
<hotspot>
<loc-id>L356957</loc-id>
<location>Sell's Lake, Ca�on City</location>
<longitude>-105.226659</longitude>
<latitude>38.438135</latitude>
<subnational1-code>US-CO</subnational1-code>
<country-code>US</country-code>
</hotspot>
Is that missing character the problem?
Anyway, I'm hoping to build and release software that uses this API, but I can't do so unless the returned data is reliable.
Thanks!!
Anonymous
I just took a survey through email about ebird. I have to say that I cannot use this part of ebird at all. I have no idea how to use htm coded information. I thought I would click on the "hotspots" list and get a map with the hotspots marked on it, like in Google Earth. Obviously, I have to be a computer genius as well as a birder to use this site. It appears that only a very small group of people can use this site.