Merge pull request #605 from pyinat/species-count

Add ObservationController.species_count()

pyinaturalist/controllers/observation_controller.py

@@ -279,6 +279,24 @@ def popular_fields(self, **params) -> ControlledTermCounts:
         response = self.client.request(get_observation_popular_field_values, **params)
         return ControlledTermCounts.from_json(response)
 
+    @copy_doc_signature(*docs._get_observations)
+    def species_count(self, **params) -> int:
+        """Get a total count of species (or other 'leaf taxa') associated with observations matching the search
+        criteria.
+
+        .. rubric:: Notes
+
+        * API reference: :v1:`GET /observations/species_counts <Observations/get_observations_species_counts>`
+        * **Leaf taxa** are the leaves of the taxonomic tree, like species, subspecies, variety, or form
+        * This method returns only the combined total number of leaf taxa in matched observations;
+          :py:meth:`.species_counts` returns the full list of taxa and the number of observations for each
+
+        Example:
+            >>> client.observations.species_count(taxon_id=52775, place_id=6853)
+        """
+        response = self.client.request(get_observation_species_counts, count_only=True, **params)
+        return response['total_results']
+
     @copy_doc_signature(*docs._get_observations)
     def species_counts(self, **params) -> TaxonCounts:
         """Get all species (or other 'leaf taxa') associated with observations matching the search
@@ -287,7 +305,7 @@ def species_counts(self, **params) -> TaxonCounts:
         .. rubric:: Notes
 
         * API reference: :v1:`GET /observations/species_counts <Observations/get_observations_species_counts>`
-        * **Leaf taxa** are the leaves of the taxonomic tree, e.g., species, subspecies, variety, etc.
+        * **Leaf taxa** are the leaves of the taxonomic tree, like species, subspecies, variety, or form
 
         Example:
             >>> client.observations.species_counts(user_login='my_username', quality_grade='research')

test/controllers/test_observation_controller.py

@@ -232,6 +232,16 @@ def test_popular_fields(requests_mock):
     assert results[0].controlled_value.label == results[0].value == 'Adult'
 
 
+def test_species_count(requests_mock):
+    requests_mock.get(
+        f'{API_V1}/observations/species_counts',
+        json=SAMPLE_DATA['get_observation_species_counts'],
+        status_code=200,
+    )
+    client = iNatClient()
+    assert client.observations.species_count(user_id='username') == 215
+
+
 def test_species_counts(requests_mock):
     requests_mock.get(
         f'{API_V1}/observations/species_counts',