ebird-api 3.0.6__py3-none-any.whl

ebird/api/__init__.py

@@ -0,0 +1,51 @@
+# flake8: noqa
+
+"""A set of wrapper functions for accessing the eBird API."""
+
+__version__ = '3.0.6'
+
+from ebird.api.constants import (
+    LOCALES
+)
+
+from ebird.api.observations import (
+    get_observations,
+    get_notable_observations,
+    get_species_observations,
+    get_nearby_observations,
+    get_nearby_notable,
+    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,
+)
+
+from ebird.api.taxonomy import (
+    get_taxonomy,
+    get_taxonomy_forms,
+    get_taxonomy_groups,
+    get_taxonomy_versions
+)
+
+from ebird.api.client import Client

ebird/api/checklists.py

@@ -0,0 +1,97 @@
+"""Functions for fetching checklists and information about visits."""
+
+from ebird.api.utils import call
+
+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'
+
+
+def get_visits(token, area, date=None, max_results=10):
+    """
+    Get the list of checklists for an area. The most recent checklists are
+    returned if a specific date is not given.
+
+    The maps to the two end points in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#4416a7cc-623b-4340-ab01-80c599ede73e
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#95a206d1-a20d-44e0-8c27-acb09ccbea1a
+    which return results in the same format.
+
+    The eBird API call also has a sortKey parameter which returns records
+    ordered by observation date or by creation date. Since checklists are
+    often submitted a few days after the actual visit this parameter is
+    not currently supported. The results are returned ordered by observation
+    date.
+
+    :param token: the token needed to access the API.
+
+    :param area: the code for a country, subnational1 region, subnational2
+    region or location.
+
+    :param date: the date, since Jan 1st 1800.
+
+    :param max_results: the maximum number of checklists to return from
+    1 to 200. The default value is 10.
+
+    :return: the info for all the checklists submitted.
+
+    :raises ValueError: if any of the arguments fail the validation checks.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    if date is not None:
+        url = CHECKLISTS_DATE_URL % (clean_area(area), clean_date(date))
+    else:
+        url = CHECKLISTS_RECENT_URL % clean_area(area)
+
+    params = {
+        'maxVisits': clean_max_checklists(max_results),
+        'sortKey': 'obs_dt',
+    }
+
+    headers = {
+        'X-eBirdApiToken': token,
+    }
+
+    return call(url, params, headers)
+
+
+def get_checklist(token, sub_id):
+    """
+    Get the contents of a checklist.
+
+    The information returned include the checklist attributes, date, etc. and the
+    list of observations. Only the code for the location and subnational1 are
+    included you will need to call get_hotspot_info() to get the full details
+    of the location.
+
+    The maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#4416a7cc-623b-4340-ab01-80c599ede73e
+
+    :param token: the token needed to access the API.
+
+    :param sub_id: the unique identifier for the checklist, e.g. S22893621.
+
+    :return: the details of the checklist, including the list of observations
+
+    :raises ValueError: if any of the arguments fail the validation checks.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    url = CHECKLIST_URL % clean_code(sub_id)
+
+    headers = {
+        'X-eBirdApiToken': token,
+    }
+
+    return call(url, {}, headers)

ebird/api/client.py

@@ -0,0 +1,338 @@
+# pylint: disable=R0902,R0904
+
+"""Classes for simplifying calls to the eBird API."""
+
+from ebird.api import observations, checklists, regions, hotspots, \
+    taxonomy, statistics
+
+from ebird.api.validation import clean_locale
+
+
+class Client:
+    """Client class to simplify interacting with the API calls.
+
+    The arguments used to initialize the client are generally API parameters
+    which stay relatively fixed for a given application, e.g. including records
+    which have not been reviewed (provisional = True) or to include records from
+    private and hotspot locations (hotspots = False).
+
+    All methods raise ValueError if any of the arguments or default values
+    cannot be validated; URLError if there is an error with the connection
+    to the eBird site or HTTPError if the eBird API returns an error.
+
+    """
+
+    def __init__(self, api_key, locale):
+        self.api_key = api_key
+        self.locale = clean_locale(locale)
+        self.max_observations = None
+        self.max_visits = 200
+        self.max_observers = 100
+        self.back = 14
+        self.category = None
+        self.detail = 'full'
+        self.dist = 25
+        self.hotspot = False
+        self.provisional = True
+        self.sort = 'date'
+
+    def get_observations(self, area):
+        """Get recent observations (up to 30 days ago) for a region or location.
+
+        :param area: a country, subnational1, subnational2 or location code
+        or a list of up to 10 codes. All codes must be same type.
+
+        :return: the list of observations in simple format.
+
+        """
+        return observations.get_observations(
+            self.api_key, area,
+            back=self.back, max_results=self.max_observations, locale=self.locale,
+            provisional=self.provisional, hotspot=self.hotspot, detail=self.detail,
+            category=self.category)
+
+    def get_notable_observations(self, area):
+        """Get recent observations of a rare species for a region or location
+
+        :param area: a country, subnational1, subnational2 or location code
+        or a list of up to 10 codes. All codes must be same type.
+
+        :return: the list of observations.
+
+        """
+        return observations.get_notable_observations(
+            self.api_key, area,
+            back=self.back, max_results=self.max_observations, locale=self.locale,
+            hotspot=self.hotspot, detail=self.detail)
+
+    def get_species_observations(self, species, area):
+        """Get recent observations for a given species in a region.
+
+        :param species: the scientific name of the species.
+
+        :param area: a country, subnational1, subnational2 or location code
+        or a list of up to 10 codes. All codes must be same type.
+
+        :return: the list of observations in simple format.
+
+        """
+        return observations.get_species_observations(
+            self.api_key, species, area,
+            back=self.back, max_results=self.max_observations, locale=self.locale,
+            provisional=self.provisional, hotspot=self.hotspot, detail=self.detail,
+            category=self.category)
+
+    def get_historic_observations(self, area, date):
+        """Get recent observations for a region.
+
+        :param area: a country, subnational1, subnational2 or location code
+        or a list of up to 10 codes. All codes must be same type.
+
+        :param date: the date, since Jan 1st 1800.
+
+        :return: the list of observations in simple format.
+
+        """
+        return observations.get_historic_observations(
+            self.api_key, area, date,
+            max_results=self.max_observations, locale=self.locale,
+            provisional=self.provisional, hotspot=self.hotspot, detail=self.detail,
+            category=self.category)
+
+    def get_nearby_observations(self, lat, lng, dist=25):
+        """Get nearby recent observations of each species.
+
+        :param lat: the latitude, which will be rounded to 2 decimal places.
+
+        :param lng: the longitude, which will be rounded to 2 decimal places.
+
+        :param dist: include all sites within this distance, from 0 to 50km
+        with a default of 25km.
+
+        :return: the list of observations in simple format.
+
+        """
+        return observations.get_nearby_observations(
+            self.api_key, lat, lng, dist=dist,
+            back=self.back, max_results=self.max_observations, locale=self.locale,
+            provisional=self.provisional, hotspot=self.hotspot,
+            category=self.category)
+
+    def get_nearby_notable(self, lat, lng, dist=25):
+        """Get the nearby, recent observations of rare species.
+
+        :param lat: the latitude, which will be rounded to 2 decimal places.
+
+        :param lng: the longitude, which will be rounded to 2 decimal places.
+
+        :param dist: include all sites within this distance, from 0 to 50km
+        with a default of 25km.
+
+        :return: the list of observations.
+
+        """
+        return observations.get_nearby_notable(
+            self.api_key, lat, lng, dist=dist,
+            back=self.back, max_results=self.max_observations, locale=self.locale,
+            hotspot=self.hotspot, detail=self.detail)
+
+    def get_nearby_species(self, species, lat, lng, dist=25):
+        """Get most recent observation of a species nearby.
+
+        :param species: the scientific name of the species.
+
+        :param lat: the latitude, which will be rounded to 2 decimal places.
+
+        :param lng: the longitude, which will be rounded to 2 decimal places.
+
+        :param dist: include all sites within this distance, from 0 to 50km
+        with a default of 25km.
+
+        :return: the list of observations in 'simple' form. See the eBird API
+        documentation for a description of the fields.
+
+        """
+        return observations.get_nearby_species(
+            self.api_key, species, lat, lng, dist=dist,
+            back=self.back, max_results=self.max_observations, locale=self.locale,
+            provisional=self.provisional, hotspot=self.hotspot,
+            category=self.category)
+
+    def get_nearest_species(self, species, lat, lng, dist=25):
+        """Get most recent observation of a species nearby.
+
+        :param species: the scientific name of the species.
+
+        :param lat: the latitude, which will be rounded to 2 decimal places.
+
+        :param lng: the longitude, which will be rounded to 2 decimal places.
+
+        :param dist: include all sites within this distance, from 0 to 50km
+        with a default of 25km.
+
+        :return: the list of observations in 'simple' form.
+
+        """
+        return observations.get_nearest_species(
+            self.api_key, species, lat, lng, dist=dist,
+            back=self.back, max_results=self.max_observations, locale=self.locale,
+            provisional=self.provisional, hotspot=self.hotspot)
+
+    def get_hotspots(self, region, back=14):
+        """List all hotspots within a region.
+
+        :param region: the code for a country, subnational1 or subnational2 region.
+
+        :param back: the past number of days to check, default is 14.
+
+        :return: the list of hotspots.
+
+        """
+        return hotspots.get_hotspots(self.api_key, region, back)
+
+    def get_nearby_hotspots(self, lat, lng, dist=25):
+        """Get the list of nearby hotspots.
+
+        :param lat: the latitude, which will be rounded to 2 decimal places.
+
+        :param lng: the longitude, which will be rounded to 2 decimal places.
+
+        :param dist: include all sites within this distance, from 0 to 50km
+        with a default of 25km.
+
+        :return: the list of hotspots nearest to the given set of coordinates.
+
+        """
+        return hotspots.get_nearby_hotspots(self.api_key, lat, lng, dist, back=self.back)
+
+    def get_hotspot(self, loc_id):
+        """Get the geographical details of a hotspot.
+
+        :param loc_id: the location code for a hotspot, eg. L374326.
+
+        :return: the latitude, longitude, name, region, etc. for the hotspot.
+
+        """
+        return hotspots.get_hotspot(self.api_key, loc_id)
+
+    def get_regions(self, rtype, region):
+        """Get the list of sub-regions or a given region.
+
+        :param rtype: the region type, either 'country', 'subnational1' or 'subnational2'.
+
+        :param region: the name of the region, either 'world', a country or a subnational1 code.
+
+        :return: the list of sub-regions within the given region.
+
+        """
+        return regions.get_regions(self.api_key, rtype, region)
+
+    def get_adjacent_regions(self, region):
+        """Get the regions adjacent to a given region.
+
+        :param region: the name of the region, either a country, a subnational1
+        or a subnational2 code.
+
+        :return: the list of regions bordering the specified region.
+
+        """
+        return regions.get_adjacent_regions(self.api_key, region)
+
+    def get_region(self, region):
+        """Get the geographical details of a country, region or sub-region.
+
+        :param region: the code for the region, eg. US-NV.
+
+        :return: the latitude, longitude, name, region, etc. for the area.
+
+        """
+        return regions.get_region(self.api_key, region)
+
+    def get_visits(self, area, date=None):
+        """
+        Get the list of checklists for an area. The most recent checklists are
+        returned if a specific date is not given.
+
+        :param area: the code for a country, subnational1 region, subnational2
+        region or location.
+
+        :param date: the date, since Jan 1st 1800.
+
+        :return: the info for all the checklists submitted.
+
+        """
+        return checklists.get_visits(self.api_key, area, date, max_results=self.max_visits)
+
+    def get_checklist(self, sub_id):
+        """
+        Get the contents of a checklist.
+
+        :param sub_id: the unique identifier for the checklist, e.g. S22893621.
+
+        :return: the details of the checklist, including the list of observations
+
+        """
+        return checklists.get_checklist(self.api_key, sub_id)
+
+    def get_top_100(self, region, date, rank='spp'):
+        """
+        Get the observers who have seen the most species or submitted the
+        greatest number of checklists on a given date.
+
+        :param region: the code for the region, eg. US-NV.
+
+        :param date: the date, since Jan 1st 1800.
+
+        :param rank: rank the observers by species seen (spp) or number of
+        checklists submitted (cl).
+
+        :return: the list of observers.
+
+        """
+        return statistics.get_top_100(
+            self.api_key, region, date, rank=rank, max_results=self.max_observers)
+
+    def get_totals(self, area, date):
+        """
+        Get the number of contributors, checklists submitted and species seen on a given date.
+
+        :param area: the code for a country subnational1 , subnational2 region or location
+
+        :param date: the date, since Jan 1st 1800.
+
+        :return: the totals for the given date
+
+        """
+        return statistics.get_totals(self.api_key, area, date)
+
+    def get_taxonomy(self):
+        """Get the full or specific subset of the taxonomy used by eBird.
+
+        :return: the complete list of species used by eBird.
+
+        """
+        return taxonomy.get_taxonomy(self.api_key, self.category, locale=self.locale)
+
+    def get_taxonomy_forms(self, code):
+        """Get all the sub-specific forms of a given species.
+
+        :return: the list of codes of each sub-species.
+
+        """
+        return taxonomy.get_taxonomy_forms(self.api_key, code)
+
+    def get_taxonomy_groups(self):
+        """Get the names of the groups of species used in the taxonomy.
+
+        :return: the list of species groups.
+
+        """
+        return taxonomy.get_taxonomy_groups(self.api_key, locale=self.locale)
+
+    def get_taxonomy_versions(self):
+        """Get all versions of the taxonomy, indicating which is the latest.
+
+        :return: a list of all the taxonomy versions used by eBird.
+
+        """
+        return taxonomy.get_taxonomy_versions(self.api_key)

ebird/api/constants.py

@@ -0,0 +1,93 @@
+"""Various constants and values used in the API."""
+
+DEFAULT_BACK = 14
+DEFAULT_DETAIL = 'simple'
+DEFAULT_DISTANCE = 25
+DEFAULT_HOTSPOTS_ONLY = 'false'
+DEFAULT_PROVISIONAL = 'false'
+DEFAULT_LOCALE = 'en'
+DEFAULT_OBSERVATION_ORDER = 'date'
+DEFAULT_SPECIES_CATEGORY = None
+DEFAULT_TAXONOMY_ORDER = 'ebird'
+DEFAULT_MAX_OBSERVATIONS = None
+DEFAULT_MAX_OBSERVERS = 100
+DEFAULT_MAX_CHECKLISTS = 10
+DEFAULT_TOP_100_RANK = 'spp'
+
+LOCALES = {
+    'Bulgarian': 'bg',
+    'Chinese': 'zh',
+    'Chinese (Simple)': 'zh_SIM',
+    'Croatian': 'hr',
+    'Czech': 'cs',
+    'Dutch': 'nl',
+    'Danish': 'da',
+    'English': 'en',
+    'English (Australia)': 'en_AU',
+    'English (India)': 'en_IN',
+    'English (IOC)': 'en_IOC',
+    'English (Hawaii)': 'en_HAW',
+    'English (Kenya)': 'en_KE',
+    'English (Malaysia)': 'en_MY',
+    'English (New Zealand)': 'en_NZ',
+    'English (Philippines)': 'en_PH',
+    'English (South Africa)': 'en_ZA',
+    'English (United Arab Emirates)': 'en_AE',
+    'English (Great Britain)': 'en_UK',
+    'English (United States)': 'en_US',
+    'Faroese': 'fo',
+    'Finnish': 'fi',
+    'French': 'fr',
+    'French (AOU)': 'fr_AOU',
+    'French (Canada)': 'fr_CA',
+    'German': 'de',
+    'French (Guadeloupe)': 'fr_GP',
+    'French (Haiti)': 'fr_HT',
+    'Haitian': 'ht_HT',
+    'Hebrew': 'iw',
+    'Hungarian': 'hu',
+    'Indonesian': 'id',
+    'Icelandic': 'is',
+    'Italian': 'it',
+    'Japanese': 'ja',
+    'Korean': 'ko',
+    'Latvian': 'lv',
+    'Lithuanian': 'lt',
+    'Malayalam': 'ml',
+    'Mongolian': 'mn',
+    'Norwegian': 'no',
+    'Polish': 'pl',
+    'Portuguese (Portugal)': 'pt_PT',
+    'Portuguese (Brasil)': 'pt_BR',
+    'Russian': 'ru',
+    'Serbian': 'sr',
+    'Slovenian': 'sl',
+    'Spanish': 'es',
+    'Spanish (Argentina)': 'es_AR',
+    'Spanish (Chile)': 'es_CL',
+    'Spanish (Costa Rica)': 'es_CR',
+    'Spanish (Cuba)': 'es_CU',
+    'Spanish (Dominican Republic)': 'es_DO',
+    'Spanish (Ecuador)': 'es_EC',
+    'Spanish (Spain)': 'es_ES',
+    'Spanish (Mexico)': 'es_MX',
+    'Spanish (Panama)': 'es_PA',
+    'Spanish (Puerto Rico)': 'es_PR',
+    'Spanish (Uruguay)': 'es_UY',
+    'Spanish (Venezuela)': 'es_VE',
+    'Swedish': 'sv',
+    'Thai': 'th',
+    'Turkish': 'tr',
+    'Ukrainian': 'uk',
+}
+
+SPECIES_CATEGORIES = [
+    'domestic', 'form', 'hybrid', 'intergrade', 'issf', 'slash', 'species', 'spuh']
+
+SPECIES_ORDERING = ['ebird', 'merlin']
+
+SPECIES_SORT = ['date', 'species']
+
+REGION_TYPES = ['country', 'subnational1', 'subnational2']
+
+TOP_100_RANK = ['spp', 'cl']