eBird Checklists is a Django starter project for building web sites that analyse data from the eBird API.
The Cornell Laboratory of Ornithology in Ithaca, New York runs the eBird database which collects observations of birds from all over the world. This data is published via an API which is free to use (once you have registered). eBird Checklists is a starter project (template) for creating a Django-based web site with a data feed from eBird for any country, or region in the world.
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.
Next, get a copy of the repository:
git clone https://git.sr.ht/~smackay/ebird-checklists
cd ebird-checklists
Create the virtual environment:
uv venv
Activate it:
source venv/bin/activate
Install the requirements:
uv sync
Run the database migrations:
python manage.py migrate
Create an admin user:
python manage.py createsuperuser
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>
EBIRD_LOCALE=en
The EBIRD_LOCALE environment variable is used when loading species information from the eBird taxonomy. The code is used to determine which language to use for the species common and family names.
Now, download data from the API:
python manage.py load_api new 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.
It's time to start the server:
python manage.py runserver
Finally, visit the home page to view the checklists:
http://localhost:8000/
This project gives you a basic web site, which is reasonably well documented. The source code will be simple to adapt if you are familiar with Django at any skill level. The rest is up to you.
To see a real site, developed using this code-base, please visit, https://www.ebirders.pt
- Documentation: https://ebird-checklists.readthedocs.io/en/latest/
- Issues: https://todo.sr.ht/~smackay/ebird-checklists
- Repository: https://git.sr.ht/~smackay/ebird-checklists
- Announcements: https://lists.sr.ht/~smackay/ebirders-discuss
- Discussions: https://lists.sr.ht/~smackay/ebirders-announce
- Development: https://lists.sr.ht/~smackay/ebirders-devel
The app is tested on Python 3.8+, and officially supports Django 4.2, 5.0 and 5.1.
eBird Checklists is released under the terms of the MIT license.