ebird-api-requests 4.0.0__py3-none-any.whl

ebird/api/requests/__init__.py

@@ -0,0 +1,39 @@
+# flake8: noqa
+
+"""A set of wrapper functions for accessing the eBird API."""
+
+__version__ = "4.0.0"
+
+from ebird.api.requests.checklists import get_checklist, get_visits
+from ebird.api.requests.client import Client
+from ebird.api.requests.constants import LOCALES
+from ebird.api.requests.hotspots import (
+    get_hotspot,
+    get_hotspots,
+    get_location,
+    get_nearby_hotspots,
+)
+from ebird.api.requests.observations import (
+    get_historic_observations,
+    get_nearby_notable,
+    get_nearby_observations,
+    get_nearby_species,
+    get_nearest_species,
+    get_notable_observations,
+    get_observations,
+    get_species_observations,
+)
+from ebird.api.requests.regions import (
+    get_adjacent_regions,
+    get_region,
+    get_regions,
+)
+from ebird.api.requests.species import get_species_list
+from ebird.api.requests.statistics import get_top_100, get_totals
+from ebird.api.requests.taxonomy import (
+    get_taxonomy,
+    get_taxonomy_forms,
+    get_taxonomy_groups,
+    get_taxonomy_locales,
+    get_taxonomy_versions,
+)

ebird/api/requests/checklists.py

@@ -0,0 +1,101 @@
+"""Functions for fetching checklists and information about visits."""
+
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import (
+    clean_area,
+    clean_code,
+    clean_date,
+    clean_max_checklists,
+)
+
+CHECKLISTS_DATE_URL = "https://api.ebird.org/v2/product/lists/%s/%s"
+CHECKLISTS_RECENT_URL = "https://api.ebird.org/v2/product/lists/%s"
+CHECKLIST_URL = "https://api.ebird.org/v2/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/requests/client.py

@@ -0,0 +1,410 @@
+# pylint: disable=R0902,R0904
+
+"""Classes for simplifying calls to the eBird API."""
+
+import socket
+
+from ebird.api.requests import (
+    checklists,
+    constants,
+    hotspots,
+    observations,
+    regions,
+    statistics,
+    taxonomy,
+)
+from ebird.api.requests.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 = constants.API_MAX_RESULTS
+        self.max_observers = constants.DEFAULT_MAX_OBSERVERS
+        self.back = constants.DEFAULT_BACK
+        self.category = None
+        self.detail = "full"
+        self.dist = constants.DEFAULT_DISTANCE
+        self.hotspot = False
+        self.provisional = True
+        self.sort = "date"
+        socket.setdefaulttimeout(constants.DEFAULT_TIMEOUT)
+
+    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/requests/constants.py

@@ -0,0 +1,108 @@
+"""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"
+
+API_MAX_RESULTS = 200
+
+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"]
+
+# Just occasionally the connection to eBird freezes. The timeout
+# will raise an error which is preferable to the sitting there
+# waiting for something to happen, when it will not.
+DEFAULT_TIMEOUT = 30