Skip to main content

eBird API Data

eBird API Data is a reusable Django app for loading data from eBird into a database.

Overview

The Cornell Laboratory of Ornithology in Ithaca, New York runs the eBird database which collects observations of birds from all over the world. All the observations are published on eBird.org, and they also make them available via an API. This project contains a loader and models to take data from the API and load it into a database. From there you can analyse the data with python, jupyter notebooks, or build a web site.

To get started, you will need to sign up for an eBird account, if you don't already have one and register to get an API key. Make sure you read and understand the Terms of use, and remember bandwidth and servers cost money, so don't abuse the service. If you need large numbers of observations, then sign up to receive the eBird Basic Dataset.

Install

You can use either pip or uv to download the package from PyPI and install it into a virtualenv:

pip install ebird-api-data

or:

uv add ebird-api-data

Update INSTALLED_APPS in your Django setting:

INSTALLED_APPS = [
    ...
    ebird.api.data
]

Finally, run the migrations to create the tables:

python manage.py migrate

Demo

If you check out the code from the repository there is a fully functioning Django site. It contains pages for checklists, observations and species, where you can browse the records or search by location, observer. date. etc. The Django Admin lets you browse and edit the records in the database.

git clone git@github.com:StuartMacKay/ebird-api-data.git
cd ebird-api-data

Create the virtual environment:

uv venv

Activate it:

source .venv/bin/activate

Install the requirements:

uv sync

Create a copy of the .env.example file and add your API key:

cp .env.example .env

For example:

EBIRD_API_KEY=<my api key>

Run the database migrations:

python manage.py migrate

Create a user:

python manage.py createsuperuser

Create a copy of the .env.example file and add your API key:

cp .env.example .env
EBIRD_API_KEY=<my api key>

Now, download data from the API:

python manage.py add_checklists --days -2 US-NY-109

This loads all the checklists, submitted in the past two days by birders in Tompkins County, New York, where the Cornell Lab is based. You can use any location code used by eBird, whether it's for a country, state/region, or county. Remember, read the terms of use.

Run the demo:

python manage.py runserver

Now, either visit the site, http:localhost:8000/, or log into the Django Admin, http:localhost:8000/admin to browse the tables.

IMPORTANT: There is a serious flaw in the eBird API - observers are identified by name. That means if more than one observer shares the same name then only one Observer record will be added to the database, and all the checklists will be assigned to them. In practice, most people ensure their name is unique by adding middle initial's etc. However it is a problem with "Anonymous eBirder". The solution is to add two Observer records with the name "Anonymous eBirder", and a fake identifier, e.g. ANON1, ANON2, etc. That way the loader will first fetch the Top 100 observers for the checklist location, on the date of the checklist, where the identifier, e.g. USER2743448, can be found, and so the checklist will be assigned to the correct Observer. If the identifier cannot be found, e.g. two observers with the same name submitted checklists at the same location on the same day, the checklist is assigned to the first Observer added with that name. Use this workaround for any other observers you encounter that share the same name. This won't work retroactively, but then you can delete the checklists, and manually reload them.

Project Information

The repository is also mirrored on Github:

The app is tested on Python 3.10+, and officially supports Django 4.2, 5.0 and 5.1.

License

eBird API Data is released under the terms of the MIT license.

Metadata

Release files for ebird-api-data 0.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ebird-api-data 0.5.3
File Size Uploaded Provenance Actions
ebird_api_data-0.5.3.tar.gz 28.5 kB Without provenance Details for ebird_api_data-0.5.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ebird-api-data 0.5.3
File Interpreter ABI Platform Actions
ebird_api_data-0.5.3-py3-none-any.whl Python 3 none any Details for ebird_api_data-0.5.3-py3-none-any.whl

Total release size: 68.2 kB

Release files / ebird_api_data-0.5.3.tar.gz

Download URL ebird_api_data-0.5.3.tar.gz
Size 28.5 kB
Tags Source
SHA-256 checksum
How to use checksums
cc201a519cc4a1db8a799d08b006ad11ceefd62a1511c4360b22d1483ef2a267
BLAKE2b-256 checksum
How to use checksums
098b48de2af807671ded2ea745fbbc79ee1f62cafcede2bb8d13cfa14b73668d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / ebird_api_data-0.5.3-py3-none-any.whl

Download URL ebird_api_data-0.5.3-py3-none-any.whl
Size 39.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
161a2e5ec53b9f84ed6661d530c7b845f04a342d74a4b2db7886faef1fc2483b
BLAKE2b-256 checksum
How to use checksums
70ed4e9d3d18f1bad6fdf9999400a434f535a2d2e250265d32aa0b5be446c6a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for ebird-api-data 0.5.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page