[](https://travis-ci.org/ProjectBabbler/ebird-api)
[](https://badge.fury.io/py/ebird-api)
[](https://img.shields.io/pypi/pyversions/ebird-api)
# eBird API
eBird API provides a set of wrapper functions for accessing the end-points
in the eBird API 2.0.
## Install
```sh
pip install ebird-api
```
## Usage
Each of the functions map to a specific end-point in the API - with one or
two exceptions where API calls are essentially identical. The functions can
be grouped into five activities: fetching observations, getting information
on hotspots, getting information on regions, getting lists of species and
getting statistics.
All 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.
To use the API you will need to register for an API key. All you need to do is
fill out this [form](https://ebird.org/api/keygen) and the API key is generated
automatically.
NOTE: Use the API with some restraint. Data costs money so don't go downloading
all the checklists for the world or other excessive behaviour or your account will
get banned. If you have a project in mind get in touch with eBird and tell them
what you want to do - they will be interested to hear it.
### Observations
```python
from ebird.api import get_observations
# Get observations from Woodman Pond, Madison county, New York for the past week.
records = get_observations(api_key, 'L227544', back=7)
# Get observations from Madison county, New York
records = get_observations(api_key, 'US-NY-053')
# Get observations from New York
records = get_observations(api_key, 'US-NY')
# Get observations from the USA - don't overdo the data downloads
records = get_observations(api_key, 'US')
```
Any where you pass in single location or region you can also pass in a
list or a comma-separated string. You can specify up to 10 locations or
regions:
```python
from ebird.api import get_observations
# Get the observations 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']
get_observations(api_key, locations, provisional=True, detail='full')
# Get the observations for Suffolk, Nassau and Queens counties in New York state.
counties = 'US-NY-103,US-NY-059,US-NY-81'
records = get_observations(api_key, locations, hotspot=False, category='species')
```
The functions that return observations, checklists or taxonomy support allow
the common name for species to be returned in different languages:
```python
from ebird.api import get_observations
records = get_observations(api_key, 'CA-QC', locale='fr')
```
In addition to getting all the observations for a given location or in
an area you can also get the latest observation of each species in a
geographical area - useful for finding the nearest place to see a given
species:
```python
from ebird.api import get_nearby_observations
# Get the most recent sightings of all species seen in the last week within
# 10km of Point Reyes National Seashore.
records = get_nearby_observations(api_key, 38.05, -122.94, dist=10, back=7)
```
The calls to get_observations() and get_nearby_observation() return all the
available records. You can limit the set of records returned to only include
notable ones (locally or nationally rare species) or limit the records to
a small number of species:
```python
from ebird.api import get_notable_observations, get_nearby_notable, \
get_species_observations, get_nearby_species
# Get the interesting birds seen in New York state.
records = get_notable_observations(api_key, 'US-NY')
# Get the observations of Horned Lark (Eremophila alpestris) in New York state.
records = get_species_observations(api_key, 'horlar', 'US-NY')
# Get the interesting birds within 50kn of Point Reyes
records = get_nearby_notable(api_key, 38.05, -122.94, dist=50)
# Find out if Barn Swallows have been seen in the area in the past 10 days
records = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
```
For the more travel-minded you can also find out where is th e nearest place
to see a given species:
```python
from ebird.api import get_nearest_species
# Where is the closest place to Cornell Lab of Ornithology to see
# Tennessee Warbler.
locations = get_nearest_species('tenwar', 42.48, -76.45)
```
Depending on what time of year you try this, you might have a long way to go.
### Checklists
There are two functions for finding out what has been seen at a given location.
First you can get the list of checklists for a given country, region or location
using get_visits(). Each result returned has the unique identifier for the
checklist. You can then call get_checklist() to get the list of observations.
```python
from ebird.api import get_visits, get_checklist
# Get visits made recently to locations in New York state:
records = get_visits(api_key, 'US-NY')
# Get visits made recently to locations in New York state on Jan 1st 2010
records = get_visits(api_key, 'US-NY', '2010-01-01')
# Get the details of a checklist
checklist = get_checklist(api_key, 'S22536787')
```
### Hotspots
There are two functions for discovering hotspots. get_hotspots() list all
the locations in a given area. You can find all the hotspots visited recently
by given a value for the back argument. get_nearby_hotspots() is used to find
hotspots within a given radius. get_hotspot() can be used to get information
on the location of a given hotspot.
```python
from ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot
# List all the hotspots in New York state.
hotspots = get_hotspots(api_key, 'US-NY')
# List all the hotspots in New York state visited in the past week.
recent = get_hotspots(api_key, 'US-NY', back=7)
# List all the hotspots in New York state visited in the past week.
recent = get_hotspots(api_key, 'US-NY', back=7)
# List all the hotspots in within 50kn of Point Reyes
nearby = get_nearby_hotspots(api_key, 38.05, -122.94, dist=50)
# Get the details of Anne V Pickard Memorial Wildlife Overlook in New York state.
details = get_hotspot(api_key, 'L2313391')
```
### Regions
eBird divides the world into countries, subnational1 regions (states) or
subnational2 regions (counties). You can use get_regions() to get the
list of sub-regions for a given region. For the approximate area covered
by a region use get_region().
```python
from ebird.api import get_regions, get_adjacent_regions, get_region
# Get the list of countries in the world.
countries = get_regions(api_key, 'country', 'world')
# Get the list of states in the US.
states = get_regions(api_key, 'subnational1', 'US')
# Get the list of counties in New York state.
counties = get_regions(api_key, 'subnational2', 'US-NY')
# Get the list of states which border New York state.
nearby = get_adjacent_regions(api_key, 'US-NY')
# Get the approximate area covered by New York state.
bounds = get_region(api_key, 'US-NY')
```
### Taxonomy
You can get details of all the species, subspecies, forms
etc. in the taxonomy used by eBird. It's the easiest way
of getting the codes for each species or subspecies,
e.g. horlar (Horned Lark), cangoo (Canada Goose), etc.,
that are used in the other API calls.1
```python
from ebird.api import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
# Get all the species in the eBird taxonomy.
taxonomy = get_taxonomy(api_key)
# Get all the species in the eBird taxonomy with common names in Spanish
names = get_taxonomy(api_key, locale='es')
# Get all the taxonomy for Horned Lark
species = get_taxonomy(api_key, species='horlar')
# Get the codes for all the subspecies and froms recognised for Barn Swallow.
forms = get_taxonomy_forms(api_key, 'barswa')
# Get information on all the taxonomy revisions, i.e. versions.
# Usually only the latest is important.
versions = get_taxonomy_versions(api_key)
```
### Statistics
You can also get some statistics from the eBird data. The most interesting
is probably get_top_100() which return the list of observers who have seen
the most species or submitted the largest number of checklists. The list is
just for a specific day so it is really only useful for "Big Days" when
lots of people are out trying to get the greatest number of species.
```python
from datetime import date
from ebird.api import get_top_100, get_totals
# Get the winner of the Global Big Day in New York, on 5th May 2018
winners = get_top_100(api_key, 'US-NY', '2018-05-05')
# Get the number of contributors, checklist submitted and species seen today
totals = get_totals(api_key, 'US-NY', date.today())
```
### Client
There is a simple Client class which wraps the various functions from the API.
You can set the API key and locale when creating a Client instance so you don't
have to keep passing them as arguments.
```python
from ebird.api import Client
api_key = 'abc123'
locale = 'es'
client = Client(api_key, locale)
client.get_observations('MX-OAX')
```
The client supports all the API functions.
## Formats
Most of the eBird API calls return JSON. Some of the calls such as getting
the hotspots for a region or getting the taxonomy also support CSV. Since
converting JSON to CSV is simple this library is opinionated in that it
only returns JSON.
## Compatibility
ebird-api works with Python 3.5+.
## Links
Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro
though it could do with a little love and attention.
Available translations for species names: http://help.ebird.org/customer/portal/articles/1596582
Information on the taxonomy used by eBird: http://help.ebird.org/customer/portal/articles/1006825-the-ebird-taxonomy
## License
eBird API is available under the terms of the [MIT](https://opensource.org/licenses/MIT) licence.
Raw data
{
"_id": null,
"home_page": "http://pypi.python.org/pypi/ebird-api/",
"name": "ebird-api",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "eBird API client",
"author": "ProjectBabbler",
"author_email": "projectbabbler@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/4c/d9/36650c5b2fdc41d0a2a74a7a6d03d72a71b10400f9d539a148cdcdfe4b40/ebird-api-3.0.6.tar.gz",
"platform": "",
"description": "[](https://travis-ci.org/ProjectBabbler/ebird-api)\n[](https://badge.fury.io/py/ebird-api)\n[](https://img.shields.io/pypi/pyversions/ebird-api)\n\n# eBird API\n\neBird API provides a set of wrapper functions for accessing the end-points\nin the eBird API 2.0.\n\n## Install\n\n```sh\npip install ebird-api\n```\n\n## Usage\n\nEach of the functions map to a specific end-point in the API - with one or\ntwo exceptions where API calls are essentially identical. The functions can \nbe grouped into five activities: fetching observations, getting information \non hotspots, getting information on regions, getting lists of species and \ngetting statistics.\n\nAll functions support arguments (with sensible defaults) for all the query \nparameters supported by the eBird API. Check the docstring for each function \nfor more details. There you will also find a link to the documentation for \neach end-point.\n\nTo use the API you will need to register for an API key. All you need to do is \nfill out this [form](https://ebird.org/api/keygen) and the API key is generated \nautomatically.\n\nNOTE: Use the API with some restraint. Data costs money so don't go downloading \nall the checklists for the world or other excessive behaviour or your account will \nget banned. If you have a project in mind get in touch with eBird and tell them \nwhat you want to do - they will be interested to hear it.\n\n### Observations\n\n```python\nfrom ebird.api import get_observations\n\n# Get observations from Woodman Pond, Madison county, New York for the past week.\nrecords = get_observations(api_key, 'L227544', back=7)\n\n# Get observations from Madison county, New York\nrecords = get_observations(api_key, 'US-NY-053')\n\n# Get observations from New York\nrecords = get_observations(api_key, 'US-NY')\n\n# Get observations from the USA - don't overdo the data downloads\nrecords = get_observations(api_key, 'US')\n```\n\nAny where you pass in single location or region you can also pass in a \nlist or a comma-separated string. You can specify up to 10 locations or \nregions:\n\n```python\nfrom ebird.api import get_observations\n\n# Get the observations for the most visited locations in Madison county, New York:\n# Woodman Pond, Ditch Bank Rd., Cornell Biological Field Station and\n# Anne V Pickard Memorial Wildlife Overlook.\nlocations = ['L227544', 'L273783', 'L677871', 'L2313391']\nget_observations(api_key, locations, provisional=True, detail='full')\n\n# Get the observations for Suffolk, Nassau and Queens counties in New York state.\ncounties = 'US-NY-103,US-NY-059,US-NY-81'\nrecords = get_observations(api_key, locations, hotspot=False, category='species')\n```\n\nThe functions that return observations, checklists or taxonomy support allow\nthe common name for species to be returned in different languages:\n\n```python\nfrom ebird.api import get_observations\n\nrecords = get_observations(api_key, 'CA-QC', locale='fr')\n```\n\nIn addition to getting all the observations for a given location or in\nan area you can also get the latest observation of each species in a \ngeographical area - useful for finding the nearest place to see a given\nspecies:\n\n```python\nfrom ebird.api import get_nearby_observations\n\n# Get the most recent sightings of all species seen in the last week within \n# 10km of Point Reyes National Seashore.\nrecords = get_nearby_observations(api_key, 38.05, -122.94, dist=10, back=7)\n```\n\nThe calls to get_observations() and get_nearby_observation() return all the \navailable records. You can limit the set of records returned to only include \nnotable ones (locally or nationally rare species) or limit the records to \na small number of species:\n\n```python\nfrom ebird.api import get_notable_observations, get_nearby_notable, \\\n get_species_observations, get_nearby_species\n\n# Get the interesting birds seen in New York state.\nrecords = get_notable_observations(api_key, 'US-NY')\n\n# Get the observations of Horned Lark (Eremophila alpestris) in New York state.\nrecords = get_species_observations(api_key, 'horlar', 'US-NY')\n\n# Get the interesting birds within 50kn of Point Reyes\nrecords = get_nearby_notable(api_key, 38.05, -122.94, dist=50)\n\n# Find out if Barn Swallows have been seen in the area in the past 10 days\nrecords = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)\n```\n\nFor the more travel-minded you can also find out where is th e nearest place \nto see a given species:\n\n```python\nfrom ebird.api import get_nearest_species\n\n# Where is the closest place to Cornell Lab of Ornithology to see\n# Tennessee Warbler. \nlocations = get_nearest_species('tenwar', 42.48, -76.45)\n```\n\nDepending on what time of year you try this, you might have a long way to go.\n\n### Checklists\n\nThere are two functions for finding out what has been seen at a given location.\nFirst you can get the list of checklists for a given country, region or location\nusing get_visits(). Each result returned has the unique identifier for the \nchecklist. You can then call get_checklist() to get the list of observations.\n\n```python\nfrom ebird.api import get_visits, get_checklist\n\n# Get visits made recently to locations in New York state:\nrecords = get_visits(api_key, 'US-NY')\n\n# Get visits made recently to locations in New York state on Jan 1st 2010\nrecords = get_visits(api_key, 'US-NY', '2010-01-01')\n\n# Get the details of a checklist\nchecklist = get_checklist(api_key, 'S22536787')\n```\n\n### Hotspots\n\nThere are two functions for discovering hotspots. get_hotspots() list all\nthe locations in a given area. You can find all the hotspots visited recently\nby given a value for the back argument. get_nearby_hotspots() is used to find\nhotspots within a given radius. get_hotspot() can be used to get information\non the location of a given hotspot.\n\n```python\nfrom ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot\n\n# List all the hotspots in New York state.\nhotspots = get_hotspots(api_key, 'US-NY')\n\n# List all the hotspots in New York state visited in the past week.\nrecent = get_hotspots(api_key, 'US-NY', back=7)\n\n# List all the hotspots in New York state visited in the past week.\nrecent = get_hotspots(api_key, 'US-NY', back=7)\n\n# List all the hotspots in within 50kn of Point Reyes\nnearby = get_nearby_hotspots(api_key, 38.05, -122.94, dist=50)\n\n# Get the details of Anne V Pickard Memorial Wildlife Overlook in New York state.\ndetails = get_hotspot(api_key, 'L2313391')\n```\n\n### Regions\n\neBird divides the world into countries, subnational1 regions (states) or \nsubnational2 regions (counties). You can use get_regions() to get the \nlist of sub-regions for a given region. For the approximate area covered \nby a region use get_region().\n\n```python\nfrom ebird.api import get_regions, get_adjacent_regions, get_region\n\n# Get the list of countries in the world.\ncountries = get_regions(api_key, 'country', 'world')\n\n# Get the list of states in the US.\nstates = get_regions(api_key, 'subnational1', 'US')\n\n# Get the list of counties in New York state.\ncounties = get_regions(api_key, 'subnational2', 'US-NY')\n\n# Get the list of states which border New York state.\nnearby = get_adjacent_regions(api_key, 'US-NY')\n\n# Get the approximate area covered by New York state.\nbounds = get_region(api_key, 'US-NY')\n```\n\n### Taxonomy\n\nYou can get details of all the species, subspecies, forms\netc. in the taxonomy used by eBird. It's the easiest way\nof getting the codes for each species or subspecies, \ne.g. horlar (Horned Lark), cangoo (Canada Goose), etc.,\nthat are used in the other API calls.1\n\n```python\nfrom ebird.api import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions\n\n# Get all the species in the eBird taxonomy.\ntaxonomy = get_taxonomy(api_key)\n\n# Get all the species in the eBird taxonomy with common names in Spanish\nnames = get_taxonomy(api_key, locale='es')\n\n# Get all the taxonomy for Horned Lark\nspecies = get_taxonomy(api_key, species='horlar')\n\n# Get the codes for all the subspecies and froms recognised for Barn Swallow.\nforms = get_taxonomy_forms(api_key, 'barswa')\n\n# Get information on all the taxonomy revisions, i.e. versions.\n# Usually only the latest is important.\nversions = get_taxonomy_versions(api_key)\n```\n\n### Statistics\n\nYou can also get some statistics from the eBird data. The most interesting\nis probably get_top_100() which return the list of observers who have seen\nthe most species or submitted the largest number of checklists. The list is\njust for a specific day so it is really only useful for \"Big Days\" when \nlots of people are out trying to get the greatest number of species.\n\n```python\nfrom datetime import date\nfrom ebird.api import get_top_100, get_totals\n\n# Get the winner of the Global Big Day in New York, on 5th May 2018\nwinners = get_top_100(api_key, 'US-NY', '2018-05-05')\n\n# Get the number of contributors, checklist submitted and species seen today\ntotals = get_totals(api_key, 'US-NY', date.today())\n```\n\n### Client\n\nThere is a simple Client class which wraps the various functions from the API.\nYou can set the API key and locale when creating a Client instance so you don't\nhave to keep passing them as arguments.\n\n```python\nfrom ebird.api import Client\n\napi_key = 'abc123'\nlocale = 'es'\n\nclient = Client(api_key, locale)\n\nclient.get_observations('MX-OAX')\n\n```\n\nThe client supports all the API functions.\n\n## Formats\n\nMost of the eBird API calls return JSON. Some of the calls such as getting \nthe hotspots for a region or getting the taxonomy also support CSV. Since \nconverting JSON to CSV is simple this library is opinionated in that it \nonly returns JSON.\n\n## Compatibility\n\nebird-api works with Python 3.5+. \n\n## Links\n\nDocumentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro \nthough it could do with a little love and attention.\n\nAvailable translations for species names: http://help.ebird.org/customer/portal/articles/1596582\n\nInformation on the taxonomy used by eBird: http://help.ebird.org/customer/portal/articles/1006825-the-ebird-taxonomy\n\n## License\n\neBird API is available under the terms of the [MIT](https://opensource.org/licenses/MIT) licence.\n\n\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "Wrapper for accessing the eBird API",
"version": "3.0.6",
"project_urls": {
"Homepage": "http://pypi.python.org/pypi/ebird-api/"
},
"split_keywords": [
"ebird",
"api",
"client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d0e526380b098bca10e83e2caf197d939b7b1becafe3b172347a29bdd3994ecc",
"md5": "775aee22788653754f16d09b4acb30a4",
"sha256": "2d5117048a05a2d2df24d3b3f9c12a2da9ea4c7fdad7cf753a392a639c42a793"
},
"downloads": -1,
"filename": "ebird_api-3.0.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "775aee22788653754f16d09b4acb30a4",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 23708,
"upload_time": "2020-09-09T21:13:45",
"upload_time_iso_8601": "2020-09-09T21:13:45.617873Z",
"url": "https://files.pythonhosted.org/packages/d0/e5/26380b098bca10e83e2caf197d939b7b1becafe3b172347a29bdd3994ecc/ebird_api-3.0.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4cd936650c5b2fdc41d0a2a74a7a6d03d72a71b10400f9d539a148cdcdfe4b40",
"md5": "ad219fddeb1ffd2e658e26b770983894",
"sha256": "3a65f0d1419fe295eef31e83577d1735f768609b3568b74ca4541f3f5407018a"
},
"downloads": -1,
"filename": "ebird-api-3.0.6.tar.gz",
"has_sig": false,
"md5_digest": "ad219fddeb1ffd2e658e26b770983894",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23481,
"upload_time": "2020-09-09T21:13:47",
"upload_time_iso_8601": "2020-09-09T21:13:47.766782Z",
"url": "https://files.pythonhosted.org/packages/4c/d9/36650c5b2fdc41d0a2a74a7a6d03d72a71b10400f9d539a148cdcdfe4b40/ebird-api-3.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-09-09 21:13:47",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ebird-api"
}
JSON