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

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

@@ -1,50 +1,60 @@
 # Change Log
 All notable changes to this project will be documented in this file.
-Only changes for the API functions are described here. Changes made 
-to the internals and developing the package are not included. Check 
+Only changes for the API functions are described here. Changes made
+to the internals and developing the package are not included. Check
 the git log for details.
 
 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.1.0] - 2024-12-30
+### Added
+- get_taxonomy_locales which returns a list of all the languages
+  supported for species common names.
+
+## [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
-  characters. Now they are at least 1 character. 
+  characters. Now they are at least 1 character.
 
 ## [3.0.5] - 2019-08-31
 ### Changed
-- Replaced the checklistSort query parameter for the top_100 end-point 
+- Replaced the checklistSort query parameter for the top_100 end-point
   with rankedBy. This change was made by eBird as checklistSort was not
   working.
 
 ## [3.0.4] - 2019-07-22
 ### Changed
-- Update the functions for fetching observations to use the sppLocale 
+- Update the functions for fetching observations to use the sppLocale
   query parameter to match the recent changes made in the eBird API.
 
 ## [3.0.3] - 2019-07-16
 ### Changed
 - When fetching observations, the list of area may only contain 10 items.
-  Previously more than 10 were allowed but this was a bug and was fixed to 
-  limit the load on the server. 
+  Previously more than 10 were allowed but this was a bug and was fixed to
+  limit the load on the server.
 
 ## [3.0.2] - 2019-06-22
 ### Changed
-- Updated the validation check for region codes so it supports ISO 3166-2. 
-- Disabled the validation check that limited the number of areas to 10 as 
+- Updated the validation check for region codes so it supports ISO 3166-2.
+- Disabled the validation check that limited the number of areas to 10 as
   the eBird API does not currently enforce this.
 
 ## [3.0.1] - 2019-06-15
-### Added 
+### Added
 - Added the full list of locales support by eBird (but not necessarily by the API).
 - Added a convenience function for saving downloaded records to a file.
 ### Changed
 - Validating the locale now uses the list supported by eBird.
 
 ## [3.0.0] - 2019-06-06
-### Added 
+### Added
 - Rewritten to support eBird API 2.0
 
 ## [2.1.1] - 2019-05-14
@@ -56,31 +66,31 @@ and by implication, [Semantic Versioning](http://semver.org/).
 - Improved the documentation in the README.
 - Project now uses the MIT license.
 
-### Added 
+### Added
 - Added scripts so each API call can be made on the command line.
 
 ## [2.0.0] - 2017-02-27
-### Changed 
+### Changed
 - Moved all the functions into the 'api' module and changed the top-level
 'ebird' module to be namespaced (PEP420).
 
 ## [1.0.2] - 2017-02-23
-### Changed 
+### Changed
 - Corrected version number in python.
 
 ## [1.0.1] - 2017-02-21
-### Added 
+### Added
 - Updated docstrings to report exceptions raised.
 
 ## [1.0.0] - 2017-02-21
-### Added 
+### Added
 - Added function for Google Gadgets showing recent observations.
 - Added function for fetching lists of species.
 - Added function for fetching nearby hotspots.
 - Added function for fetching lists of hotspots for a region.
 ### Changed
-- Renamed list_locations() to list_regions() and find_locations() to 
-find_regions() as "locations" refer to specific sites in the functions 
+- Renamed list_locations() to list_regions() and find_locations() to
+find_regions() as "locations" refer to specific sites in the functions
 that fetch observations.
 
 ## [0.2.0] - 2017-02-18

{ebird-api-3.0.6 → ebird_api-3.1.0}/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.1.0/PKG-INFO

@@ -0,0 +1,374 @@
+Metadata-Version: 2.1
+Name: ebird-api
+Version: 3.1.0
+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
+import os
+
+from ebird.api import get_observations
+
+# Always store secrets outside the code, so you don't accidentally
+# commit them. Environment variables are ideal for this.
+api_key = os.environ["EBIRD_API_KEY"]
+    
+# Get observations from Woodman Pond, Madison county, New York for the past week.
+this_week = get_observations(api_key, 'L227544', back=7)
+
+# Get observations from Madison county, New York
+country_records = get_observations(api_key, 'US-NY-053')
+
+# Get observations from New York
+state_records = get_observations(api_key, 'US-NY')
+
+# Get observations from the USA - don't overdo the data downloads
+national_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
+import os
+
+from ebird.api import get_observations
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# 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
+import os
+
+from ebird.api import get_observations
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+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
+import os
+
+from ebird.api import get_nearby_observations
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# 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
+import os
+
+from ebird.api import (
+    get_notable_observations, 
+    get_nearby_notable,
+    get_species_observations, 
+    get_nearby_species,
+)
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# Get the interesting birds seen in New York state.
+notables = 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
+nearby_notables = 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
+nearby_species = 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
+import os 
+
+from ebird.api import get_nearest_species
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# Where is the closest place to Cornell Lab of Ornithology to see
+# Tennessee Warbler. 
+locations = get_nearest_species(api_key, '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
+import os
+
+from ebird.api import get_visits, get_checklist
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# Get visits made recently to locations in New York state:
+visits = get_visits(api_key, 'US-NY')
+
+# Get visits made recently to locations in New York state on Jan 1st 2010
+recent_visits = 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
+import os
+
+from ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# 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 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
+import os
+
+from ebird.api import get_regions, get_adjacent_regions, get_region
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# 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
+import os
+
+from ebird.api import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# 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
+import os
+
+from datetime import date
+from ebird.api import get_top_100, get_totals
+
+api_key = os.environ["EBIRD_API_KEY"]
+
+# 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
+import os
+
+from ebird.api import Client
+
+api_key = os.environ["EBIRD_API_KEY"]
+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 currently supported versions of Python, 3.8+. However, 
+it is known to work with earlier versions, at least 3.5 - 3.7, without any 
+problems.
+
+## 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.