- Fast download time, much faster than a Google Gadget
- Flexible design, so you can customize it so it blends into your website
Using eBird APIs, a set of XML databases containing recent bird observations, we'll output the latest rarities in a region and give it a little formatting. In the end, your result should look something like this:
Step 1: What API do you want to use? To find out what an eBird API XML file looks like, click here. This example shows rarities were found in New York within the last 7 days. The URL of this API is:
- The first part (http://ebird.org/ws1.1/data/notable/region/recent) is the root URL which specifies an API which outputs rarities in a subnational region (e.g. state, province, county).
- The remainder of the URL defines parameters:
- rtype=subnational1 specifies whether we would like to refer to a state/province (subnational1) or a county (subnational2). Change this depending on what region type you would like to use.
- r specifies the subnational region name/ID.
If you wish to enter a state/province, enter the country code, a hyphen, and the state code with no spaces (e.g. Montana = US-MT, North Dakota = US-ND, British Columbia = CA-BC, Noord-Holland Netherlands = NL-NH). If you do not know what state code to enter, click here, search for your state code, and copy over the "subnational-1" value of that line.
If you wish to enter a county, click here and change the country code in the web address URL bar if you are not looking for a county within the United States. Find the county with the name you are looking for and the corresponding state code (subnational1 value) in the same line. Copy the subnational-2 code into your API URL. An example of a subnational2-code might be US-NY-109 for Tompkins County, New York.
- back specifies how many days back you would like to look. You can only look back a maximum of 30 days. Change this accordingly
- detail specifies how much detail you would like to see in the API. Putting in detail=full rather than detail=simple returns items such as observer names and checklist IDs, which we definitely don't want to miss! Type in detail=full, you don't stand a thing to lose.
Step 2: The HTML Code
The code you will write in this tutorial contains a very short HTML snippet:
Now it's time to append our data to our "html" string. Using the variables defined above, we'll now put them into the string containing the HTML formatting and layout. This is the bit of code to modify in order to make the end result look different. Notice that we are still inside the "for" loop initiated in the previous step, so we create a new <tr> element for every sighting. Copy this code beneath the code you pasted above:
Earlier we used the function getRaritiesData() to magically retrieve the ith sighting tag data. Here's the function that does that. Copy it beneath your other codes:
If you are using Blogger, Chrome platforms, other Google code products, web apps, or extensions, you can skip this step. Instead, research whether or not you will be able to access eBird's APIs without requesting permissions or cross-domain exemptions--remember that security measures are taken for cross-domain XMLHttpRequests, and you won't just be able to access eBird's APIs from your own domain.
If you are hosting your own site, or are on a platform that does not provide open cross-domain access to any website, you will need to request access to eBird.org. To get access to eBird's APIs from your domain, send an email to email@example.com indicating you would like to be added to their http://ebird.org/crossdomain.xml file only after you have finished writing the code and are sure your website does not work using standard cross-domain XHR. eBird may implement the access-control-allow-origin:* header in the near future, so watch for this. If you have doubts about this, just email firstname.lastname@example.org anytime. You should receive a personal confirmation email from eBird verifying that you have been added to the crossdomain.xml file, thereby giving you developer privileges to access any page in the site via XHR.
Step 9: Finishing, Debugging, and Styling
If worse comes to worst, I'm a great debugger as well!! If you have issues, or a debugging error to ask me about, I'm here to answer any questions. Email email@example.com.
A Recap: The Code in One Chunk
Here's the code all in one chunk:
I have tried the above code in standard webpages on all major browsers, and it worked. I could not get this version to work on Google blogs (this website included), so unfortunately I can't provide an on-site demo.
If you have gone through this entire tutorial, and done a little debugging, and your code still doesn't work, feel free to email me at firstname.lastname@example.org. Provide as many details as you can. Also comment if you have been successful and would like to share your finished product with the rest of us. We love success stories! Overall, I hope this technology can be used on many webpages to help users get a more friendly recent sightings report. This is the best alternative to Google Gadgets, and I hope many of you make efforts to implement this code. Go eBird!