ebird-api-requests 4.1.0__tar.gz → 4.2.0__tar.gz

{ebird_api_requests-4.1.0/src/ebird_api_requests.egg-info → ebird_api_requests-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebird-api-requests
-Version: 4.1.0
+Version: 4.2.0
 Summary: A python library for accessing the eBird API, version 2.0
 Author-email: Stuart MacKay <smackay@flagstonesoftware.com>
 License: MIT License

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/pyproject.toml

@@ -29,7 +29,7 @@ license = {text = "MIT License"}
 name = "ebird-api-requests"
 readme = "README.md"
 requires-python = ">= 3.10"
-version = "4.1.0"
+version = "4.2.0"
 
 [project.urls]
 Repository = "https://github.com/StuartMacKay/ebird-api-requests.git"
@@ -37,7 +37,7 @@ Issues = "https://github.com/StuartMacKay/ebird-api-requests/issues"
 Changelog = "https://github.com/StuartMacKay/ebird-api-requests/blob/master/CHANGELOG.md"
 
 [tool.bumpversion]
-current_version = "4.1.0"
+current_version = "4.2.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 ignore_missing_version = false

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/src/ebird/api/requests/__init__.py

@@ -2,7 +2,7 @@
 
 """A set of wrapper functions for accessing the eBird API."""
 
-__version__ = "4.1.0"
+__version__ = "4.2.0"
 
 from ebird.api.requests.checklists import get_checklist, get_visits
 from ebird.api.requests.client import Client

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/src/ebird/api/requests/client.py

@@ -109,7 +109,7 @@ class Client:
             category=self.category,
         )
 
-    def get_historic_observations(self, area, date):
+    def get_historic_observations(self, area, date, rank="mrec"):
         """Get recent observations for a region.
 
         :param area: a country, subnational1, subnational2 or location code
@@ -117,6 +117,9 @@ class Client:
 
         :param date: the date, since Jan 1st 1800.
 
+        :param rank: for each species, return the latest observation on the
+        date, 'mrec' (the default), or the first observation, 'create'.
+
         :return: the list of observations in simple format.
 
         """
@@ -130,6 +133,7 @@ class Client:
             hotspot=self.hotspot,
             detail=self.detail,
             category=self.category,
+            rank=rank,
         )
 
     def get_nearby_observations(self, lat, lng, dist=25):

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/src/ebird/api/requests/constants.py

@@ -7,6 +7,7 @@ DEFAULT_HOTSPOTS_ONLY = "false"
 DEFAULT_PROVISIONAL = "false"
 DEFAULT_LOCALE = "en"
 DEFAULT_OBSERVATION_ORDER = "date"
+DEFAULT_OBSERVATION_RANK = "mrec"
 DEFAULT_SPECIES_CATEGORY = None
 DEFAULT_TAXONOMY_ORDER = "ebird"
 DEFAULT_MAX_OBSERVATIONS = None
@@ -102,6 +103,8 @@ REGION_TYPES = ["country", "subnational1", "subnational2"]
 
 TOP_100_RANK = ["spp", "cl"]
 
+OBSERVATION_RANK = ["mrec", "create"]
+
 # 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.

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/src/ebird/api/requests/hotspots.py

@@ -1,5 +1,6 @@
 """Functions for fetching information about hotspots."""
 
+from json import JSONDecodeError
 from urllib.error import HTTPError
 
 from ebird.api.requests.utils import call
@@ -124,8 +125,8 @@ def get_hotspot(token, loc_id):
     """Get the geographical details of a hotspot.
 
     The call only work for hotspots. If you use the identifier for a private
-    location the eBird API will return HTTP 410 Gone and an HttpError will be
-    raised.
+    location the eBird API will return an empty response (as of Oct 2026) and
+    a JSONDecodeError will be raised.
 
     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
@@ -143,6 +144,8 @@ def get_hotspot(token, loc_id):
 
     :raises HTTPError if the eBird API returns an error.
 
+    :raises JSONDecodeError if the JSON data returned by the API is invalid.
+
     """
     url = HOTSPOT_INFO_URL % clean_location(loc_id)
 
@@ -185,11 +188,13 @@ def get_location(token, loc_id):
 
     # get_region() does not return "isHotspot" in the results, so we
     # try get_hotspot() first and if the call fails with HTTP 410 Gone,
-    # indicating it's a private location, we call get_region and
-    # massage the result.
+    # or as of Oct 2026, HTTP 200 and an empty response, indicating
+    # it's a private location, we call get_region and massage the result.
 
     try:
         return get_hotspot(token, loc_id)
+    except JSONDecodeError:
+        pass
     except HTTPError as err:
         if err.code != 410:
             raise

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/src/ebird/api/requests/observations.py

@@ -14,6 +14,7 @@ from ebird.api.requests.validation import (
     clean_lng,
     clean_locale,
     clean_max_observations,
+    clean_observation_rank,
     clean_provisional,
     clean_sort,
 )
@@ -633,6 +634,7 @@ def get_historic_observations(
     hotspot=False,
     detail="simple",
     category=None,
+    rank="mrec",
 ):
     """Get recent observations for a region.
 
@@ -671,6 +673,9 @@ def get_historic_observations(
     More than one value can be given in a comma-separated string. The default
     value is None and records from all categories will be returned.
 
+    :param rank: for each species, return the latest observation on the
+    date, 'mrec' (the default), or the first observation, 'create'.
+
     :return: the list of observations in simple format.
 
     :raises ValueError: if any of the arguments fail the validation checks.
@@ -686,7 +691,7 @@ def get_historic_observations(
     url = HISTORIC_OBSERVATIONS_URL % (cleaned[0], date.strftime("%Y/%m/%d"))
 
     params = {
-        "rank": "mrec",
+        "rank": clean_observation_rank(rank),
         "detail": clean_detail(detail),
         "sppLocale": clean_locale(locale),
         "includeProvisional": clean_provisional(provisional),

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/src/ebird/api/requests/statistics.py

@@ -5,7 +5,7 @@ from ebird.api.requests.validation import (
     clean_area,
     clean_date,
     clean_max_observers,
-    clean_rank,
+    clean_observer_rank,
     clean_region,
 )
 
@@ -46,7 +46,7 @@ def get_top_100(token, region, date, rank="spp", max_results=100):
 
     params = {
         "maxObservers": clean_max_observers(max_results),
-        "rankedBy": clean_rank(rank),
+        "rankedBy": clean_observer_rank(rank),
     }
 
     headers = {

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/src/ebird/api/requests/utils.py

@@ -182,6 +182,8 @@ def call(url, params, headers, max_retries=3, backoff_factor=1.0):
 
     :raises HTTPError if the eBird API returns an error.
 
+    :raises JSONDecodeError if the JSON data returned by the API is invalid.
+
     """
     filtered = filter_parameters(params)
     mapped = map_parameters(filtered)

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0}/src/ebird/api/requests/validation.py

@@ -3,12 +3,14 @@
 """Functions for validation."""
 
 import re
+import warnings
 from datetime import date, datetime
 from enum import Enum
 
 from ebird.api.requests import constants
 
 _locales = constants.LOCALES.values()
+_observation_rank = ", ".join(constants.OBSERVATION_RANK)
 _region_types = ", ".join(constants.REGION_TYPES)
 _sort_list = ", ".join(constants.SPECIES_SORT)
 _species_categories = ", ".join(constants.SPECIES_CATEGORIES)
@@ -38,7 +40,7 @@ def is_region(value):
     return (
         re.match(r"^[A-Z]{2}$", value)
         or re.match(r"^[A-Z]{2}-[A-Z0-9]{1,3}$", value)
-        or re.match(r"^[A-Z]{2}-[A-Z0-9]{2,3}-[A-Z0-9]{2,3}$", value)
+        or re.match(r"^[A-Z]{2}-[A-Z0-9]{1,3}-[A-Z0-9]{2,3}$", value)
     )
 
 
@@ -200,6 +202,15 @@ def clean_detail(value):
     return cleaned
 
 
+def clean_observation_rank(value):
+    cleaned = clean_code(value, transform=Transform.LOWER)
+    if cleaned not in constants.OBSERVATION_RANK:
+        raise ValueError(
+            "Value for 'rank', %s, must be one of: %s" % (value, _observation_rank)
+        )
+    return cleaned
+
+
 def clean_provisional(value):
     return "true" if bool(value) else "false"
 
@@ -339,10 +350,21 @@ def clean_date(value):
     return cleaned.strftime("%Y/%m/%d")
 
 
-def clean_rank(value):
+def clean_observer_rank(value):
     cleaned = clean_code(value, transform=Transform.LOWER)
     if cleaned not in constants.TOP_100_RANK:
         raise ValueError(
             "Top 100 rank, %s, must be one or more of : %s" % (value, _top_100_rank)
         )
     return cleaned
+
+
+def clean_rank(value):
+    # Deprecated in favour of clean_observer_rank(). Remove in 5.0.0.
+    warnings.warn(
+        "clean_rank() is deprecated and will be removed in 5.0.0. "
+        "Use clean_observer_rank() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return clean_observer_rank(value)

{ebird_api_requests-4.1.0 → ebird_api_requests-4.2.0/src/ebird_api_requests.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebird-api-requests
-Version: 4.1.0
+Version: 4.2.0
 Summary: A python library for accessing the eBird API, version 2.0
 Author-email: Stuart MacKay <smackay@flagstonesoftware.com>
 License: MIT License