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

ebird/api/requests/regions.py

@@ -0,0 +1,110 @@
+"""Functions for fetching information about regions."""
+
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import clean_region, clean_region_type
+
+REGION_LIST_URL = "https://api.ebird.org/v2/ref/region/list/%s/%s"
+ADJACENT_REGIONS_URL = "https://api.ebird.org/v2/ref/adjacent/%s"
+REGION_INFO_URL = "https://api.ebird.org/v2/ref/region/info/%s"
+
+
+def get_regions(token, rtype, region):
+    """Get the list of sub-regions or a given region.
+
+    This maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#e25218db-566b-4d8b-81ca-e79a8f68c599
+
+    Not all combinations of region type and region code are supported.
+    You can get all the subnational2 regions of a country but you cannot
+    get the subnational2 regions for the world.
+
+    :param token: the token needed to access the API.
+
+    :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.
+
+    :raises ValueError: if an invalid region type is given.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    url = REGION_LIST_URL % (clean_region_type(rtype), clean_region(region))
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(url, {}, headers)
+
+
+def get_adjacent_regions(token, region):
+    """Get the regions adjacent to a given region.
+
+    This maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#3aca0519-3105-47fc-8611-a4dfd500a32f
+
+    :param token: the token needed to access the API.
+
+    :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.
+
+    :raises ValueError: if an invalid region code.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    url = ADJACENT_REGIONS_URL % clean_region(region)
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(url, {}, headers)
+
+
+def get_region(token, region):
+    """Get the geographical details of a country, region or sub-region.
+
+    This maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#e25218db-566b-4d8b-81ca-e79a8f68c599
+
+    There are two query parameters supported by the API, regionNameFormat
+    and delim. These are used to control how the name of the region that the
+    region code corresponds to is presented, e.g. US-NY returns "New York,
+    United States". The utility of these is rather limited so they are
+    currently not supported.
+
+    :param token: the token needed to access the API.
+
+    :param region: the code for the region, eg. US-NV.
+
+    :return: the latitude, longitude, name, region, etc. for the area.
+
+    :raises ValueError: if an invalid region code is given.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    url = REGION_INFO_URL % clean_region(region)
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(url, {}, headers)

ebird/api/requests/species.py

@@ -0,0 +1,37 @@
+"""Functions for fetching information about species."""
+
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import clean_area
+
+SPECIES_LIST_URL = "https://api.ebird.org/v2/product/spplist/%s"
+
+
+def get_species_list(token, area):
+    """
+    Get the list of species for an area.
+
+    The maps to the two end points in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#55bd1b26-6951-4a88-943a-d3a8aa1157dd
+
+    :param token: the token needed to access the API.
+
+    :param area: the code for a country, subnational1 region, subnational2
+    region or location.
+
+    :return: codes, e.g. horlar1, for the list of species observed in the area.
+
+    :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 = SPECIES_LIST_URL % clean_area(area)
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(url, {}, headers)

ebird/api/requests/statistics.py

@@ -0,0 +1,90 @@
+"""Functions for fetching basic statistics about observers and observations."""
+
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import (
+    clean_area,
+    clean_date,
+    clean_max_observers,
+    clean_rank,
+    clean_region,
+)
+
+TOP_100_URL = "https://api.ebird.org/v2/product/top100/%s/%s"
+TOTALS_URL = "https://api.ebird.org/v2/product/stats/%s/%s"
+
+
+def get_top_100(token, region, date, rank="spp", max_results=100):
+    """
+    Get the observers who have seen the most species or submitted the
+    greatest number of checklists on a given date.
+
+    The maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#2d8d3f94-c4b0-42bd-9c8e-71edfa6347ba
+
+    :param token: the token needed to access the API.
+
+    :param region: the code for the region, eg. US-NV.
+
+    :param date: the date, since Jan 1st 1800.
+
+    :param rank: order results by species seen (spp) or checklists submitted (cl).
+
+    :param max_results: the maximum number of entries to return from
+    1 to 100. The default value is 100.
+
+    :return: the list of observers.
+
+    :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 = TOP_100_URL % (clean_region(region), date.strftime("%Y/%m/%d"))
+
+    params = {
+        "maxObservers": clean_max_observers(max_results),
+        "rankedBy": clean_rank(rank),
+    }
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(url, params, headers)
+
+
+def get_totals(token, area, date):
+    """
+    Get the number of contributors, checklists submitted and species seen
+    on a given date.
+
+    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 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
+
+    :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 = TOTALS_URL % (clean_area(area), clean_date(date))
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(url, {}, headers)

ebird/api/requests/taxonomy.py

@@ -0,0 +1,213 @@
+"""Functions for fetching information about the taxonomy used by eBird."""
+
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import (
+    clean_categories,
+    clean_codes,
+    clean_locale,
+    clean_ordering,
+    clean_species_code,
+)
+
+TAXONOMY_URL = "https://api.ebird.org/v2/ref/taxonomy/ebird"
+TAXONOMY_FORMS_URL = "https://api.ebird.org/v2/ref/taxon/forms/%s"
+TAXONOMY_GROUPS_URL = "https://api.ebird.org/v2/ref/sppgroup/%s"
+TAXONOMY_VERSIONS_URL = "https://api.ebird.org/v2/ref/taxonomy/versions"
+TAXONOMY_LOCALES_URL = "https://api.ebird.org/v2/ref/taxa-locales/ebird"
+
+
+def get_taxonomy(token, category=None, locale="en", version=None, species=None):
+    """Get the full or specific subset of the taxonomy used by eBird.
+
+    The maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#952a4310-536d-4ad1-8f3e-77cfb624d1bc
+
+    :param token: the token needed to access the API.
+
+    :param category: one or more categories of species to return: 'domestic',
+    'form', 'hybrid', 'intergrade', 'issf', 'slash', 'species' or 'spuh'.
+    More than one value can be given in a comma-separated string.
+
+    :param locale: the language (to use) for the species common names. The
+    default of 'en' will use species names from the eBird/Clements checklist.
+    This can be any locale for which eBird has translations available. For a
+    complete list see, http://help.ebird.org/customer/portal/articles/1596582.
+
+    :param version: the version number of the taxonomy to return,
+    see get_taxonomy_versions()
+
+    :param species: a comma-separate string or list containing scientific
+    names or 6-letter species codes.
+
+    :return: the list of entries matching the category.
+
+    :raises ValueError: if an invalid category or locale is given.
+
+    :raises ValueError: if both a category and species are used. In this case
+    the eBird API ignore the species and returns only results for the category.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    params = {"locale": clean_locale(locale), "fmt": "json"}
+
+    if category is not None:
+        params["cat"] = ",".join(clean_categories(category))
+
+    if version is not None:
+        params["version"] = version
+
+    if species is not None:
+        params["species"] = ",".join(clean_codes(species))
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(TAXONOMY_URL, params, headers)
+
+
+def get_taxonomy_forms(token, species):
+    """Get all the sub-specific forms of a given species.
+
+    The maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#e338e5a6-919d-4603-a7db-6c690fa62371
+
+    NOTE: the get_taxonomy() API call returns 6-letter species codes.
+
+    :param token: the token needed to access the API.
+
+    :param species: the 6-letter eBird species code, e.g. horlar (Horned Lark).
+
+    :return: the list of codes of each sub-species.
+
+    :raises ValueError is the species code is invalid (not 6 letters).
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    url = TAXONOMY_FORMS_URL % clean_species_code(species)
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(url, {}, headers)
+
+
+def get_taxonomy_groups(token, ordering="ebird", locale="en"):
+    """Get the names of the groups of species used in the taxonomy.
+
+    The maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#aa9804aa-dbf9-4a53-bbf4-48e214e4677a
+
+    NOTE: Not all the locales supported by the eBird site or apps
+    are available in the API. The following locales are not
+    supported, (language, locale code):
+
+    Croatian, hr
+    Croatian, hr
+    Faroese, fo
+    Finnish, fi
+    Haitian, ht_HT
+    Hungarian, hu
+    Indonesian, id
+    Italian, it
+    Japanese, ja
+    Korean, ko
+    Latvian, lv
+    Lithuanian, lt
+    Malayalam, ml
+    Mongolian, mn
+    Polish, pl
+    Slovenian, sl
+    Swedish, sv
+    Ukrainian, uk
+
+    :param token: the token needed to access the API.
+
+    :param ordering: order groups using taxonomic order, 'ebird' or by
+    likeness, 'merlin'.
+
+    :param locale: the language (to use) for the group names.
+
+    :return: the list of species groups.
+
+    :raises ValueError: if an invalid ordering or locale is given.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    url = TAXONOMY_GROUPS_URL % clean_ordering(ordering)
+
+    params = {
+        "groupNameLocale": clean_locale(locale),
+    }
+
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(url, params, headers)
+
+
+def get_taxonomy_versions(token):
+    """Get all versions of the taxonomy, indicating which is the latest.
+
+    The maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#9bba1ff5-6eb2-4f9a-91fd-e5ed34e51500
+
+    :param token: the token needed to access the API.
+
+    :return: a list of all the taxonomy versions used by eBird.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(TAXONOMY_VERSIONS_URL, {}, headers)
+
+
+def get_taxonomy_locales(token):
+    """Get all locales supported for common names.
+
+    The maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#3ea8ff71-c254-4811-9e80-b445a39302a6
+
+    This API call returns a list of all the languages supported
+    by eBird. An entry in the list takes the form:
+
+        {'code': 'af', 'lastUpdate': '2024-12-21 06:06', 'name': 'Afrikaans'}
+
+    There are currently, (2024-12-30), 107 languages available.
+
+    :param token: the token needed to access the API.
+
+    :return: a list of all the taxonomy locales used by eBird.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(TAXONOMY_LOCALES_URL, {}, headers)

ebird/api/requests/utils.py

@@ -0,0 +1,164 @@
+"""Various functions used in the API."""
+
+import json
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from ebird.api.requests import constants
+
+_parameter_defaults = {
+    "back": constants.DEFAULT_BACK,
+    "cat": constants.DEFAULT_SPECIES_CATEGORY,
+    "detail": constants.DEFAULT_DETAIL,
+    "dist": constants.DEFAULT_DISTANCE,
+    "groupNameLocale": constants.DEFAULT_LOCALE,
+    "hotspot": constants.DEFAULT_HOTSPOTS_ONLY,
+    "includeProvisional": constants.DEFAULT_PROVISIONAL,
+    "sort": constants.DEFAULT_OBSERVATION_ORDER,
+    "locale": constants.DEFAULT_LOCALE,
+    "sppLocale": constants.DEFAULT_LOCALE,
+    "maxObservations": constants.DEFAULT_MAX_OBSERVATIONS,
+    "maxObservers": constants.DEFAULT_MAX_OBSERVERS,
+    "maxVisits": constants.DEFAULT_MAX_CHECKLISTS,
+    "rankedBy": constants.DEFAULT_TOP_100_RANK,
+}
+
+_parameter_map = {
+    "maxObservations": "maxResults",
+    "maxObservers": "maxResults",
+    "maxVisits": "maxResults",
+}
+
+
+def map_parameters(params):
+    """Translate the names of the query parameters to match those used
+    in the API.
+
+    :param params: a dict contains the GET parameters for the request that
+    will be sent to the eBird API.
+
+    :return: a copy of the params dictionary with only the parameters
+    that are not set to a default value.
+
+    """
+    mapped = {}
+
+    for key, value in params.items():
+        key = _parameter_map.get(key, key)
+        mapped[key] = value
+
+    return mapped
+
+
+def filter_parameters(params):
+    """Filter out any parameter which matches the eBird API default value.
+
+    :param params: a dict contains the GET parameters for the request that
+    will be sent to the eBird API.
+
+    :return: a copy of the params dictionary with only the parameters
+    that are not set to a default value.
+
+    """
+    filtered = {}
+
+    defaults = _parameter_defaults.copy()
+
+    for key, value in params.items():
+        if key in defaults:
+            if value != defaults[key]:
+                filtered[key] = value
+        else:
+            filtered[key] = value
+
+    return filtered
+
+
+def get_response(url, params=None, headers=None):
+    """Get the content from the eBird API.
+
+    :param url: the URL for the API call.
+    :type url: str
+
+    :param params: the query parameters for the API call.
+    :type params: dict
+
+    :param headers: the headers to add to the request.
+    :type params: dict
+
+    :return: the content returned by the API
+    :rtype: str
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    if params:
+        url += "?" + urlencode(params, doseq=True)
+
+    request = Request(url)
+
+    if headers:
+        for name, value in headers.items():
+            request.add_header(name, value)
+
+    return urlopen(request).read()
+
+
+def get_json(content):
+    """Decode the JSON records from the response.
+
+    :param content: the content returned by the eBird API.
+    :type content: http.client.HTTPResponse:
+
+    :return: the records decoded from the JSON payload.
+    :rtype: list
+
+    """
+    return json.loads(content.decode("utf-8"))
+
+
+def save_json(filename, data, indent=None):
+    """Save results to a file.
+
+    :param filename: the name of the file to save. The .json
+    extension will be added if not present.
+
+    :param data: the list of records to save.
+
+    :param indent: whether to pretty-print results by adding indentation
+    for each level. The default is no formatting.
+
+    """
+    if not filename.endswith(".json"):
+        filename += ".json"
+    with open(filename, "w") as outfile:
+        json.dump(data, outfile, indent=indent)
+
+
+def call(url, params, headers):
+    """Call the eBird API.
+
+    :param url: the URL for the API call.
+    :type url: str
+
+    :param params: the query parameters for the API call.
+    :type params: dict
+
+    :param headers: the headers to add to the request.
+    :type params: dict
+
+    :return: the content returned by the API
+    :rtype: dict | list
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    filtered = filter_parameters(params)
+    mapped = map_parameters(filtered)
+    return get_json(get_response(url, mapped, headers))