Giters

ropensci / rebird

Wrapper to the eBird API

Home Page:https://docs.ropensci.org/rebird

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

New API coming

ateucher opened this issue · comments

commented

I just noticed that there is a new API coming: https://documenter.getpostman.com/view/664302/ebird-api-20/2HTbHW

I don't know the timeline for full implementation, but it looks like the ones documented there are already functional. It looks like it will require an API key for most calls

commented

cool 👍

commented

Thanks for the heads up @ateucher. I'm not very familiar with APIs, so I'll definitely need some help implementing the changes, and it seems this change will require a fair bit of work. Aside from adding the key, we basically need to change the urls in the ebird_GET() function as well as in each separate function as the directories have slightly changed. Fortunately it seems that most variable names haven't changed. We'll also have to write a small paragraph explaining how to obtain your key, for which you need to have an eBird account.

Some requests (like https://ebird.org/ws2.0/ref/taxonomy/ebird) can also be used without a key; this one will return a .csv with the current taxonomy. There are also new options (such as obtaining older versions of the taxonomy, see https://ebird.org/ws2.0/ref/taxonomy/versions) that would be neat to implement into the package as well.

Probably makes sense to release 2.0 API compatibility as v1.0.0?

EDIT: I'll also ask the folks at eBird when they're planning to retire 1.1.

commented

So I spent the day looking through the differences between APIs. Here are what I think are the main differences that matter for updating the functions in rebird:

  1. The URL path structure has changed, which means we'll have to tinker with the if statements in every function.
  2. Related with the point above, regions are now specified in the URL path rather than being specified via query arguments.
  3. The new API doesn't use scientific names as query arguments anymore; instead it uses a species code, which isn't intuitive so we will have to match scientific names from a taxonomic table stored in the package.
  4. While including the key is very simple (i.e. passed using a header), we need to create a straightforward way for users to store their key. Have either of you implemented this in an R package before?
  5. Slightly unrelated to the change: the ebird_GET function parses the JSON object to a list only to turn it back to a data frame (by passing a simplifyVector = FALSE to jsonlite::fromJSON()). Is there a reason for this? We can probably make the function much simpler by using simplifyVector = TRUE.

tl;dr: This API change will require updating every function in the package.

commented

The merge of PR #67 closes this issue.