Skip to main content

Wrapper for accessing the eBird API

Project description

# eBird API

eBird API provides a set of wrapper functions for accessing the end-points
in the eBird API.

# Install

```sh
pip install ebird-api
```

## Usage

Each of the core functions map to a specific end-point.

### Observations

The majority of the end-points are used to fetch the observations made
at a given site or in a general area:

```python
from ebird import \
geo_observations, geo_species, geo_notable, \
hotspot_observations, hotspot_species, hotspot_notable, \
location_observations, location_species, location_notable, \
region_observations, region_species, region_notable, \
nearest_species

# Get the most recent sighting of the the first 100 species within 5km
# of here in the past week. Coordinates will be rounded to 2 decimal places.
records = geo_observations(42.48, -76.45, dist=5, back=7, max_results=100)

# Get the most recent sighting of each species within 25km of here in
# the past week but only from hotspots and with common names in Spanish.
records = geo_observations(
42.48, -76.45, back=7, locale='es', provisional=True, hotspot=True)

# Get the most recent sighting of Canada Goose near here in the past 2 weeks.
records = geo_species('Branta canadensis', 42.48, -76.45)

# Get the latest sightings of local or nationally rare birds seen near here
# in the past 10 days. Return all the available fields for each record.
records = geo_notable(42.48, -76.45, back=10, detail='full')

# Codes for some of the main hotspots in Seattle, Washington.
hotspots = ['L128530', 'L351484', 'L162766', 'L269461', 'L571490']

# Get all the records of what has been seen in the past week. Only the
# basic set of fields ('simple' format) are returned.
records = hotspot_observations(hotspots, back=7)

# Get all the records for Canada Goose in the past 2 weeks. Include
# records that have not been reviewed and return all the fields available.
records = hotspot_species(
'Branta canadensis', hotspots, provisional=True, detail='full')

# Get all the most sightings of locally or nationally rare birds for the past
# 30 days. Include all the fields available.
records = hotspot_notable(hotspots, back=30, detail='full')

# Code for the most visited locations in Madison county, New York:
# Woodman Pond, Ditch Bank Rd., Cornell Biological Field Station and
# Anne V Pickard Memorial Wildlife Overlook.
locations = ['L227544', 'L273783', 'L677871', 'L2313391']

# The functions for fetching records for locations are identical to
# those for hotspots. The only difference is you can include codes for
# any location, hotspot or private. Codes for private locations are
# ignored if you pass them to the hotspot functions.

records = location_observations(locations, back=7)

records = location_species(
'Branta canadensis', locations, provisional=True, detail='full')

records = location_notable(locations, back=30, detail='full')

# Get the most recent sightings of each species for Madison county, New
# York for the past week.
records = region_observations('US-NY-053', back=7)

# Get all most recent sighting of Canada Goose in New York state within
# the past two weeks.
records = region_species('Branta canadensis', 'US-NY')

# Get all the records of locally or nationally rare birds for New York
# county (including Central Park) for the past week.
records = region_notable('US-NY-061', back=7)

# Where is the closest place to Cornell Lab of Ornithology to see
# Tennessee Warbler. Depending on when you try this you might have
# far to travel.
records = nearest_species('Oreothlypis peregrina', 42.48, -76.45)
```

### Reference data

The API also has functions for fetching the reference data (species, areas
and locations) used in the eBird database:

```python
from ebird import find_regions, list_regions, list_species, list_hotspots

# Get the list of states in the US.
states = list_regions('subnational1', 'US')

# Get the list of counties in New York state.
counties = list_regions('subnational2', 'US-NY')

# Find all the counties in the USA with 'west' in their name.
counties = find_regions('subnational2', 'US')

# List all the hotspots in New York state.
hotspots = list_hotspots('US-NY')

# List all the hotspots in New York state visited in the past week.
hotspots = list_hotspots('US-NY', back=7)

# Get all the species in the eBird taxonomy.
species = list_species()

# Get all the species classified as 'domestic'.
species = list_species('domestic')

```

### Product data

The product end-point is used by Google Gadgets (widgets) that can be
added to a web site to show what species have been seen for a given
location or area:

```python
from ebird import hotspot_summary

# Get a summary of the records at a hotspot for the past week.
records = hotspot_summary('L128530', back=7)

```

Each of these functions support arguments (with sensible defaults) for all
the query parameters supported by the eBird API. Check the docstring for
each function for more details. There you will also find a link to the
documentation for each end-point.

## Compatibility

ebird-api works with Python 2.7, 3.3, 3.4, 3.5, 3.6. It works with Python 2.6
but the tests use assertDictEqual() which were introduced only in Python 2.7.
It also works with Python 3.2 but tox which is used to run the tests does not.

## Resources

Documentation for the eBird API: https://confluence.cornell.edu/display/CLOISAPI/eBird+API+1.1

Available translations for species names: http://help.ebird.org/customer/portal/articles/1596582

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ebird-api-1.0.2.tar.gz (27.7 kB view details)

Uploaded Source

Built Distribution

ebird_api-1.0.2-py2.py3-none-any.whl (6.3 kB view details)

Uploaded Python 2Python 3

File details

Details for the file ebird-api-1.0.2.tar.gz.

File metadata

  • Download URL: ebird-api-1.0.2.tar.gz
  • Upload date:
  • Size: 27.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for ebird-api-1.0.2.tar.gz
Algorithm Hash digest
SHA256 7f68d2d47183ef3a64ee6a77602b0568d2d60e0760ea22aa36a612479ef54ae1
MD5 224bc456ef22a676e57e00f4c85a28e8
BLAKE2b-256 e3a692452026eafb418f6cc4f486ebc889693dfd08ac005460af1fe4f6f7fc39

See more details on using hashes here.

File details

Details for the file ebird_api-1.0.2-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for ebird_api-1.0.2-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 e3489b8fd796d35572b34ae5b84d03f12b737772be89ea9be5e7f0323e8056d9
MD5 305ec7ca6302615797fd5750a58fbea3
BLAKE2b-256 2410858f7147dc1ad32e2536c329f6605bbe8abc51bb0c8423bb455923bae727

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page