Customised eBird alerts

eBird alerts are great. I have a bunch set up for regions near my home and I often temporarily enable them for places that I'll be travelling to. And yet... they don't quite tell me what I really want to know. ​

Which is this:

• Nearby notable sightings, regardless of which region they occur in. I live closer to two country borders than to the other side of my state. You can approximate your personal definition of 'nearby' by separately signing up to a myriad of state- and county-level 'Rare Bird Alerts', but it's cumbersome and inflexible.
• Potential lifers sighted nearby. eBird's 'Needs Alerts' notify you when a species is sighted that you have never seen in that particular region. But if I travel for the first time to (say) Spain, I might be very interested in alerts for Great Spotted Cuckoo, but less keen to scroll through ten thousand sightings of Common Blackbirds and Great Tits. Unfortunately, it's not possible to set up 'Needs Alerts' to only tell you about birds not on your life list. I'm not sure if this is a deliberate decision by eBird to encourage you to get out birding more. Or maybe am I just after a niche feature that not many people want?

In any case, this situation has been unchanged for many years, so I finally took matters into my own hands.

**Warning: Extreme nerding ahead**

So I wrote some R functions. They rely on the very helpful package rebird, which allows you to query recent eBird sightings via eBird's API. To calculate travel distances, they draw on R's API to Google Maps: mapsapi. Here's what they do:

• nearby_notables() takes an address as input and outputs all recent nearby notable sightings (according to eBird's definition of 'notable') along with an estimated travel time from your address. Optionally, you can input a life list (in eBird's export format), in which case birds already on your life list will be excluded from the output. Lastly, you can input a maximum travel distance and mode of travel (one of "driving", "walking", "bicycling" or "transit") to only see birds that are reachable within that time from your address.​
• region_lifers() takes a list of regions and a life list as input and spits out all potential lifers that have been sighted recently in those regions. As above, you can optionally also input an address, maximum travel time, and mode of travel to only see birds reachable within that time from your address.

Using these functions is unfortunately a little more complicated than just installing an R package. First, I have no intention of making a package (can't be arsed, sorry). Second, you will need API keys for both aeBird and Google Maps. If this hasn't put you off already, here's what you need to do:

• Get an eBird API key here. Once you have it,  store it in the form
  EBIRD_KEY = EE2D2915A43D 
  in your .Renviron file
  (Copy in your own key, the one above is fake!)
• Get a Google Maps API key here. The keys are free, but you need to enter a payment method for verification. Store your key in your .Renviron file in the form
  MAPS_API_KEY = "47BCHWQObKEekPUFpT5g7LLcUlGnmX3C4oOpLOV"
  (Put your own key in between the quotes.)
• If you only want to see sightings of bird species that you've never seen before, then download your eBird life list here (click on 'Download (csv)' in the top right corner). Note that for compatibility reasons, you will need to set your preferences for common names to English (United States) before downloading your life list.
• Import your life list into R (the default settings of read.csv() are just fine).
• Lastly, download the R script here. You might need to install some packages. There are examples at the end of this script file.

Here are some examples (corresponding to those in the script file link above):

Notable species near a given address:

Note that the address can be entered in any format recognisable by Google Maps.  Mode can be set to "driving" (the default), "walking", "bicycling" or "transit". Travel times are in the format hours:minutes (or days:hours:minutes if the travel time is longer than 24 hours). Travel times that cannot be calculated by Google Maps appear as NA.

Notable species near a given address, excluding birds on your life list:

Notable species that are within a specified travel time of a given address:

The maximum travel time should be inputted in minutes (the argument 'time = 180' in the example above corresponds to 3 hours).

Potential lifers (notable or not) in a given eBird region:

You can also enter multiple eBird regions as a list. Note that the function region_lifers() can be slow, because it needs to query each potential lifer individually to the eBird API. In contrast, nearby_notables() is quite fast.

Potential lifers in a given eBird region along with travel times from a given address:

Potential lifers in a given eBird region that are within a specified travel time of a given address:

If anyone else ends up using this: Feedback and bug reports are welcome!