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

{ebird_api-4.1.0 → ebird_api-4.2.0}/CHANGELOG.md

@@ -8,6 +8,17 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 This project adheres to [PEP440](https://www.python.org/dev/peps/pep-0440/)
 and by implication, [Semantic Versioning](http://semver.org/).
 
+## [4.2.0] - 2026-10-12
+- Changed get_historic_observations() so observations can be returned by
+  date created or date last modified.
+- Renamed clean_rank() to clean_observer_rank(). clean_rank() is deprecated
+  and will be removed in 5.0.0.
+- Allow single-character subnational1 codes, e.g. IE-L.
+
+## [4.1.1] - 2026-10-10
+- Changed get_location() to handle an API change where an empty response
+  is now returned for private locations instead of HHTP 410 Gone.
+
 ## [4.1.0] - 2026-06-14
 - Retry requests, with exponentinal back-off, if an error occurs.
 
@@ -146,21 +157,3 @@ avoid any issues with representation.
 ## [0.1.0] - 2017-02-13
 ### Added
 - Core functions for accessing end-points for fetching observations.
-
-[Unreleased]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.6...HEAD
-[3.0.6]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.5...3.0.6
-[3.0.5]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.5...3.0.5
-[3.0.5]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.4...3.0.5
-[3.0.4]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.3...3.0.4
-[3.0.3]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.3...3.0.3
-[3.0.3]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.2...3.0.3
-[3.0.2]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.1...3.0.2
-[3.0.1]: https://github.com/ProjectBabbler/ebird-api/compare/3.0.0...3.0.1
-[2.1.1]: https://github.com/ProjectBabbler/ebird-api/compare/2.0.1...2.1.1
-[2.1.0]: https://github.com/ProjectBabbler/ebird-api/compare/2.0.0...2.1.0
-[2.0.0]: https://github.com/ProjectBabbler/ebird-api/compare/1.0.2...2.0.0
-[1.0.2]: https://github.com/ProjectBabbler/ebird-api/compare/1.0.1...1.0.2
-[1.0.1]: https://github.com/ProjectBabbler/ebird-api/compare/1.0.0...1.0.1
-[1.0.0]: https://github.com/ProjectBabbler/ebird-api/compare/0.2.0...1.0.0
-[0.2.0]: https://github.com/ProjectBabbler/ebird-api/compare/0.1.1...0.2.0
-[0.1.1]: https://github.com/ProjectBabbler/ebird-api/compare/0.1.0...0.1.1

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebird-api
-Version: 4.1.0
+Version: 4.2.0
 Summary: Wrapper for accessing the eBird API
 Author-email: Project Babbler <projectbabbler@gmail.com>
 License: MIT License

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

@@ -29,7 +29,7 @@ license = {text = "MIT License"}
 name = "ebird-api"
 readme = "README.md"
 requires-python = ">= 3.10"
-version = "4.1.0"
+version = "4.2.0"
 
 [project.urls]
 Repository = "https://github.com/ProjectBabbler/ebird-api.git"
@@ -37,7 +37,7 @@ Issues = "https://github.com/ProjectBabbler/ebird-api/issues"
 Changelog = "https://github.com/ProjectBabbler/ebird-api/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-4.1.0 → ebird_api-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-4.1.0 → ebird_api-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-4.1.0 → ebird_api-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-4.1.0 → ebird_api-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-4.1.0 → ebird_api-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-4.1.0 → ebird_api-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-4.1.0 → ebird_api-4.2.0}/src/ebird/api/requests/utils.py

@@ -88,7 +88,7 @@ def get_response(url, params=None, headers=None, max_retries=3, backoff_factor=1
     :param headers: the headers to add to the request.
     :type headers: dict
 
-    :param max_retries: number of times to retry after a 429 response.
+    :param max_retries: number of times to retry after an error response.
     :type max_retries: int
 
     :param backoff_factor: seconds to wait before the first retry; doubles
@@ -167,7 +167,7 @@ def call(url, params, headers, max_retries=3, backoff_factor=1.0):
     :param headers: the headers to add to the request.
     :type headers: dict
 
-    :param max_retries: number of times to retry after a 429 response.
+    :param max_retries: number of times to retry after an error response.
     :type max_retries: int
 
     :param backoff_factor: seconds to wait before the first retry; doubles
@@ -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-4.1.0 → ebird_api-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)
@@ -27,18 +29,18 @@ def is_country(value):
 
 
 def is_subnational1(value):
-    return re.match(r"^[A-Z]{2}-[A-Z0-9]{2,3}$", value)
+    return re.match(r"^[A-Z]{2}-[A-Z0-9]{1,3}$", value)
 
 
 def is_subnational2(value):
-    return re.match(r"^[A-Z]{2}-[A-Z0-9]{2,3}-[A-Z0-9]{2,3}$", value)
+    return re.match(r"^[A-Z]{2}-[A-Z0-9]{1,3}-[A-Z0-9]{2,3}$", value)
 
 
 def is_region(value):
     return (
         re.match(r"^[A-Z]{2}$", value)
-        or re.match(r"^[A-Z]{2}-[A-Z0-9]{2,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}$", 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-4.1.0 → ebird_api-4.2.0/src/ebird_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebird-api
-Version: 4.1.0
+Version: 4.2.0
 Summary: Wrapper for accessing the eBird API
 Author-email: Project Babbler <projectbabbler@gmail.com>
 License: MIT License