ebird-api 3.0.6__py3-none-any.whl

ebird/api/regions.py

@@ -0,0 +1,109 @@
+"""Functions for fetching information about regions."""
+
+from ebird.api.utils import call
+
+from ebird.api.validation import clean_region, clean_region_type
+
+
+REGION_LIST_URL = 'https://ebird.org/ws2.0/ref/region/list/%s/%s.json'
+ADJACENT_REGIONS_URL = 'https://ebird.org/ws2.0/ref/adjacent/%s'
+REGION_INFO_URL = 'https://ebird.org/ws2.0/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/statistics.py

@@ -0,0 +1,86 @@
+"""Functions for fetching basic statistics about observers and observations."""
+
+from ebird.api.utils import call
+
+from ebird.api.validation import clean_area, clean_date, clean_max_observers, \
+    clean_region, clean_rank
+
+TOP_100_URL = 'https://ebird.org/ws2.0/product/top100/%s/%s'
+TOTALS_URL = 'https://ebird.org/ws2.0/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/taxonomy.py

@@ -0,0 +1,181 @@
+"""Functions for fetching information about the taxonomy used by eBird."""
+
+from ebird.api.utils import call
+
+from ebird.api.validation import clean_categories, clean_locale, clean_ordering, \
+    clean_species_code, clean_codes
+
+TAXONOMY_URL = 'https://ebird.org/ws2.0/ref/taxonomy/ebird'
+TAXONOMY_FORMS_URL = 'https://ebird.org/ws2.0/ref/taxon/forms/%s'
+TAXONOMY_GROUPS_URL = 'https://ebird.org/ws2.0/ref/sppgroup/%s'
+TAXONOMY_VERSIONS_URL = 'https://ebird.org/ws2.0/ref/taxonomy/versions'
+
+
+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 = {
+        'sppLocale': 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)

ebird/api/utils.py

@@ -0,0 +1,165 @@
+"""Various functions used in the API."""
+
+import json
+
+from urllib.request import Request, urlopen
+from urllib.parse import urlencode
+
+from ebird.api 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,
+    '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: str
+
+    :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))