ebird-api 3.0.6__tar.gz → 3.0.7__tar.gz

{ebird-api-3.0.6 → ebird_api-3.0.7}/CHANGELOG.md

@@ -8,6 +8,11 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 This project adheres to [PEP440](https://www.python.org/dev/peps/pep-0440/)
 and by implication, [Semantic Versioning](http://semver.org/).
 
+## [3.0.7] - 2024-10-09
+### Changed
+- get_taxonomy now passes "locale" as a parameter, not "sppLocale",
+  which was ignored so all names were returned in English.
+
 ## [3.0.6] - 2020-09-09
 ### Changed
 - Subnational1 and subnational2 codes were assumed to be at least two

{ebird-api-3.0.6 → ebird_api-3.0.7}/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 ProjectBabbler
+Copyright (c) 2019-2024 ProjectBabbler
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{ebird-api-3.0.6 → ebird_api-3.0.7}/MANIFEST.in

@@ -1,2 +1,2 @@
 include CHANGELOG.md LICENSE.txt
-recursive-include ebird *.py
+recursive-include src *.py

ebird_api-3.0.7/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.1
+Name: ebird-api
+Version: 3.0.7
+Summary: Wrapper for accessing the eBird API
+Author-email: Project Babbler <projectbabbler@gmail.com>
+License: MIT License
+Project-URL: Repository, https://github.com/ProjectBabbler/ebird-api.git
+Project-URL: Issues, https://github.com/ProjectBabbler/ebird-api/issues
+Project-URL: Changelog, https://github.com/ProjectBabbler/ebird-api/blob/master/CHANGELOG.md
+Keywords: eBird,API,client
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Natural Language :: English
+Classifier: Topic :: Utilities
+Classifier: Topic :: Internet
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+
+[![Build Status](https://travis-ci.org/ProjectBabbler/ebird-api.svg?branch=master)](https://travis-ci.org/ProjectBabbler/ebird-api)
+[![PyPI version](https://badge.fury.io/py/ebird-api.svg)](https://badge.fury.io/py/ebird-api)
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/ebird-api.svg)](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 common name for species can be returned in different languages by specifying locale in the functions that return observations, checklists or taxonomy:
+
+```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 the 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.
+
+```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 returns 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.

{ebird-api-3.0.6 → ebird_api-3.0.7}/README.md

@@ -71,8 +71,7 @@ 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:
+The common name for species can be returned in different languages by specifying locale in the functions that return observations, checklists or taxonomy:
 
 ```python
 from ebird.api import get_observations
@@ -115,8 +114,7 @@ records = get_nearby_notable(api_key, 38.05, -122.94, dist=50)
 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:
+For the more travel-minded you can also find out the nearest place to see a given species:
 
 ```python
 from ebird.api import get_nearest_species
@@ -207,7 +205,7 @@ 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
+that are used in the other API calls.
 
 ```python
 from ebird.api import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
@@ -232,7 +230,7 @@ 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
+is probably get_top_100() which returns 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.

ebird_api-3.0.7/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools >= 61.0"]
+
+[project]
+authors = [
+  {name = "Project Babbler", email = "projectbabbler@gmail.com"},
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Natural Language :: English",
+    "Topic :: Utilities",
+    "Topic :: Internet",
+]
+description = 'Wrapper for accessing the eBird API'
+keywords = ["eBird", "API", "client"]
+license = {text = "MIT License"}
+name = "ebird-api"
+readme = "README.md"
+requires-python = ">= 3.8"
+version = "3.0.7"
+
+[project.urls]
+Repository = "https://github.com/ProjectBabbler/ebird-api.git"
+Issues = "https://github.com/ProjectBabbler/ebird-api/issues"
+Changelog = "https://github.com/ProjectBabbler/ebird-api/blob/master/CHANGELOG.md"
+
+[tool.black]
+# Notes:
+#
+# line-length: this is just the default but it's included here so it's easy
+# to see that the value is synced with other code quality tools.
+#
+# target-version: the python version is set when the project is generated
+# so we might as well make use of it.
+#
+# exclude: the regex for excluding migrations is added in case you don't
+# want them reformatted.
+#
+# For all options see:
+#   https://black.readthedocs.io/en/stable/installation_and_usage.html
+
+line-length = 88
+target-version = ["py312"]

{ebird-api-3.0.6 → ebird_api-3.0.7}/setup.cfg

@@ -1,6 +1,3 @@
-[bdist_wheel]
-universal = 1
-
 [egg_info]
 tag_build = 
 tag_date = 0

ebird_api-3.0.7/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

{ebird-api-3.0.6 → ebird_api-3.0.7/src}/ebird/api/__init__.py

@@ -2,50 +2,27 @@
 
 """A set of wrapper functions for accessing the eBird API."""
 
-__version__ = '3.0.6'
-
-from ebird.api.constants import (
-    LOCALES
-)
+__version__ = "3.0.7"
 
+from ebird.api.checklists import get_checklist, get_visits
+from ebird.api.client import Client
+from ebird.api.constants import LOCALES
+from ebird.api.hotspots import get_hotspot, get_hotspots, get_nearby_hotspots
 from ebird.api.observations import (
-    get_observations,
-    get_notable_observations,
-    get_species_observations,
-    get_nearby_observations,
+    get_historic_observations,
     get_nearby_notable,
+    get_nearby_observations,
     get_nearby_species,
     get_nearest_species,
-    get_historic_observations,
-)
-
-from ebird.api.checklists import (
-    get_visits,
-    get_checklist,
-)
-
-from ebird.api.hotspots import (
-    get_hotspots,
-    get_nearby_hotspots,
-    get_hotspot,
-)
-
-from ebird.api.regions import (
-    get_regions,
-    get_region,
-    get_adjacent_regions,
-)
-
-from ebird.api.statistics import (
-    get_top_100,
-    get_totals,
+    get_notable_observations,
+    get_observations,
+    get_species_observations,
 )
-
+from ebird.api.regions import get_adjacent_regions, get_region, get_regions
+from ebird.api.statistics import get_top_100, get_totals
 from ebird.api.taxonomy import (
     get_taxonomy,
     get_taxonomy_forms,
     get_taxonomy_groups,
-    get_taxonomy_versions
+    get_taxonomy_versions,
 )
-
-from ebird.api.client import Client

{ebird-api-3.0.6 → ebird_api-3.0.7/src}/ebird/api/checklists.py

@@ -1,12 +1,16 @@
 """Functions for fetching checklists and information about visits."""
 
 from ebird.api.utils import call
+from ebird.api.validation import (
+    clean_area,
+    clean_code,
+    clean_date,
+    clean_max_checklists,
+)
 
-from ebird.api.validation import clean_code, clean_max_checklists, clean_area, clean_date
-
-CHECKLISTS_DATE_URL = 'https://ebird.org/ws2.0/product/lists/%s/%s'
-CHECKLISTS_RECENT_URL = 'https://ebird.org/ws2.0/product/lists/%s'
-CHECKLIST_URL = 'https://ebird.org/ws2.0/product/checklist/view/%s'
+CHECKLISTS_DATE_URL = "https://ebird.org/ws2.0/product/lists/%s/%s"
+CHECKLISTS_RECENT_URL = "https://ebird.org/ws2.0/product/lists/%s"
+CHECKLIST_URL = "https://ebird.org/ws2.0/product/checklist/view/%s"
 
 
 def get_visits(token, area, date=None, max_results=10):
@@ -51,12 +55,12 @@ def get_visits(token, area, date=None, max_results=10):
         url = CHECKLISTS_RECENT_URL % clean_area(area)
 
     params = {
-        'maxVisits': clean_max_checklists(max_results),
-        'sortKey': 'obs_dt',
+        "maxVisits": clean_max_checklists(max_results),
+        "sortKey": "obs_dt",
     }
 
     headers = {
-        'X-eBirdApiToken': token,
+        "X-eBirdApiToken": token,
     }
 
     return call(url, params, headers)
@@ -91,7 +95,7 @@ def get_checklist(token, sub_id):
     url = CHECKLIST_URL % clean_code(sub_id)
 
     headers = {
-        'X-eBirdApiToken': token,
+        "X-eBirdApiToken": token,
     }
 
     return call(url, {}, headers)