Add rank parameter to get_historic_observations

src/ebird/api/client.py

@@ -43,6 +43,7 @@ def __init__(self, api_key, locale):
         self.hotspot = False
         self.provisional = True
         self.sort = "date"
+        self.rank = "mrec"
         socket.setdefaulttimeout(constants.DEFAULT_TIMEOUT)
 
     def get_observations(self, area):
@@ -130,6 +131,7 @@ def get_historic_observations(self, area, date):
             hotspot=self.hotspot,
             detail=self.detail,
             category=self.category,
+            rank=self.rank,
         )
 
     def get_nearby_observations(self, lat, lng, dist=25):

src/ebird/api/observations.py

@@ -15,6 +15,7 @@
     clean_locale,
     clean_max_observations,
     clean_provisional,
+    clean_observation_rank,
     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,10 @@ 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: return the last (rank='mrec') or first(rank='create')
+    observation on the date. See the eBird API documentation for a description
+    of the fields.
+
     :return: the list of observations in simple format.
 
     :raises ValueError: if any of the arguments fail the validation checks.
@@ -686,7 +692,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),

src/ebird/api/validation.py

@@ -200,6 +200,15 @@ def clean_detail(value):
     return cleaned
 
 
+def clean_observation_rank(value):
+    cleaned = clean_code(value, transform=Transform.LOWER)
+    if cleaned not in ("mrec", "create"):
+        raise ValueError(
+            "Value for 'rank', %s, must be either 'mrec' or 'create'" % value
+        )
+    return cleaned
+
+
 def clean_provisional(value):
     return "true" if bool(value) else "false"
 

tests/unit/validation/test_clean_observation_rank.py

@@ -0,0 +1,13 @@
+import unittest
+
+from ebird.api.validation import clean_observation_rank
+
+
+class CleanObservationRankTests(unittest.TestCase):
+    """Tests for the rank validation function."""
+
+    def test_codes_are_lower_case(self):
+        self.assertEqual("mrec", clean_observation_rank("Mrec"))
+
+    def test_invalid_code_raises_error(self):
+        self.assertRaises(ValueError, clean_observation_rank, "none")