projectbabbler/ebird-api

A wrapper for the public API to the eBird database.

ebird-api's Issues

Add instructions on importing the API specification into the Swagger editor.

Add instructions to the OpenAPI 3.0 Specification on how to import the API specification into the Swagger Editor (include install instructions for that too) and generating client libraries from it.

region_type_for_code and get_location_type do the same thing

The utils function, region_type_for_code is identical to the validation function, get_location_type. However the definition of the regexes in region_type_for_code are slightly different the subnational1 part of the code is assumed to be 2 or more characters while in get_location_type it is assumed to be 2 or 3 characters (as described in ISO 3166-2).

See which one is used most and remove the other.

Add description for the API security schemes

The specification has a section in the schemas for describing how the API key is used. The current description was based on the default specification that comes with the Swagger Editor and needs fixing/updating.

Locations are limited to 10 but API allows an unlimited number.

For API end-points, for example, getting recent observations, a list of regions or locations may be given in a query parameter. The official documentation for the API states that the list may contain up to 10 items. This is not correct the API does not limit the number to 10.

This was tested with 20 subnational1 regions and it worked just fine. This is noted in the Errata (item 6).

Currently the limitation is disabled in the validation checks. However the behaviour should be confirmed with the eBird developers just in case they fix the limit and any extra code are ignored or start throwing errors. Once the results is known update the validation checks or remove the currently commented out code.

Add target to setup the virtualenv

Add a target to the makefile to setup the virtualenv. Also see if there are any other initialization tasks that could be performed.

Update the locale to sppLocale

The eBird API recently changed so now sppLocale is now supported when fetching observations and is the "official" way of specifying the language for species common names.

Update all the endpoints in the observations module to replace the query parameter, locale with sppLocale. Don't change the locale keyword argument to the functions.

Add help target to makefile

Create a Self-Documenting Makefile by adding a help target that list all the available targets.

Clean up acceptance tests

Refactor the acceptance tests so the entire suite can be run using

python -m tests.acceptance

Add description for the API repsonse

The description for the format of the responses from the API is just a placeholder. Add a full description. You can find sample responses from the official API documentation.

Send updated documentation to eBird

Having the Errata is all very well for pointing out the errors in the official documentation but it's always a lot of work writing good documentation (and generally thankless too). Save them some work by generating updated/corrected documentation.

Update the documentation and examples for the GET Recent observations in a region end-point, send it to them, get feedback and continue updating the remaining end-points if they give the go-ahead.

Tasks

• Sign up for a postman account.

• Create a collection from official docs.
  Use the "Run in Postman" option.
  This took a little bit of work to set up, https://blog.getpostman.com/2018/10/16/run-in-postman-is-now-available-for-linux/

• Publish the cloned collection.
  See https://documenter.getpostman.com/view/7944380/S1a7UkGE?version=latest

• Update the documentation for GET Recent observations in a region
  See https://documenter.getpostman.com/view/7944380/S1a7UkGE?version=latest#3e0f51a3-d3ae-485f-b7b0-0a38d2f3ba99

• Set up context/environment variables.
  An environment (with associated environment variables) can be selected when the documentation is published.

  • Create an environment, 'ebird'.
  • Include it in the publish settings.
  • Include definitions for {{serverName}} and {{contextRoot}}
  • Find the nearest location to Cornell
    Sapsucker Woods--Lab Building Area, Tompkins County, New York, USA
    Location Id: L1379126
    Subnational2: US-NY-109
    Subnational1: US-NY
    Country: US
    Lat: 42.4796874
    Lng: -76.4509829
  • Create environment variables for the hierarchy of regions
  • Sign up for a new api key. Add it to the environment.

• Add examples for each of the main query parameters

• Test if collection can be exported and imported.

• Tell the eBird team.
  Send links, ask for feedback, ask for permission to continue the work.
  Include a description of #8. Also describe #6.
  Include the collection export as an attachment as ask them to see if it can be imported. That would make it easy to incorporate changed.
  Update: Issues 6 and 8 were not reported - the email was sufficiently long and detailed that adding more would have been confusing the to goal of getting permission to continue.

Issues

• Decide whether to include the api key header as part of the documentation or leave it as a defined variable in the request parameters.
  [Solved] Add a section for headers. The header and params in the Postman are really designed for requests made to the end-points. It's most consistent to make the documentation explicit and leave the request documentation for the examples.

Add flake8 check when making release

Add a target to the makefile that runs flake8 against the api code and the tests too.

Add rankedBy query parameter on Top 100 end-point.

As part of the work for sending updates for the official documentation the checklistSort query parameter was found not to be working. eBird replaced this with the rankedBy query parameter, which orders the results by species seen (spp, the default) or by number of checklists submitted (cl).

Add the query parameter to the end-point and update all the tests and documentation.

Max distance is limited to 50km but the API allows 500km

The maximum distance for example for getting nearby hotspots is 50km however the eBird API allows values up to 500km though the documentation says the limit is 50km.

Find out which is correct and update the validation checks and documentation if necessary,

https://api.ebird.org/v2/data/obs/geo/recent?lat={{lat}}&lng={{lng}} ... stops displaying a specific, current checklist species after a few days of entry.

Checklist with valid days back not returned by API https://api.ebird.org/v2/data/obs/geo/recent?lat={{lat}}&lng={{lng}}

Steps:
Submit checklist with multiple observations for current date via Ebird.org on android phone. Always use the same location and mark Yes to "Are you submitting a complete checklist of the birds..". The entire checklist displays correctly in ebird.org/myebird

In personal web app that uses ebird API v2 search for recent checklist observations..

Results:
The next day: ..Entire check list for the location returned the day after entered. Days back = 1. - expected
Following days:
A day of so later only 1 species is returned from the checklist, same checklist/date, irrespective of the number of days back (even if 30). - Not expected.
Days later: NO entries are displayed for that same checklist and the list is never returned again for any days back - Not expected.

The entire checklist continues to display correctly in ebird.org/myebird throughout.

Expected:
The entire checklist should be returned for 30 days following in entry

Note :
https://api.ebird.org/v2/data/obs/geo/recent/{{speciesCode}}?lat={{lat}}&lng={{lng}} returns the observation of any species on the checklist if a species is specified

Exclude dev-requirements.txt from the release

setup.py includes all .txt file in the root directory in the release. Update this to exlcude dev-requirements.txt since it is only used for development.

Finish the schema for Observations

The schema for the fields returned for observations contains only the fields for the 'simple' format. See if it is possible to include the fields for the 'full' format but still being able to differentiate between the two.

Refactor validation tests

text_validation.py is getting big and the coverage on all the functions used to validate the parameters passed to the API is not that great.

Split the file into separate tests for each validation function but consider grouping test for some functions e.g. is_region, is_country into a single file to keep the overall number of files down.

Finish the API specification for "Get recent observations"

Add a full specification for the end-point. This will be a useful template that can be used to generate the specification for the other end-points.