Air pollution history. Fixes #362

Author: csparpa

pyowm/airpollutionapi30/airpollution_client.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 from pyowm.airpollutionapi30.uris import CO_INDEX_URL, OZONE_URL, NO2_INDEX_URL, SO2_INDEX_URL, AIR_POLLUTION_URL, \
-    AIR_POLLUTION_FORECAST_URL
+    AIR_POLLUTION_FORECAST_URL, AIR_POLLUTION_HISTORY_URL
 from pyowm.utils import formatting
 
 
@@ -177,6 +177,18 @@ def get_forecast_air_pollution(self, params_dict):
         _, json_data = self._client.get_json(AIR_POLLUTION_FORECAST_URL, params=params_dict)
         return json_data
 
+    def get_historical_air_pollution(self, params_dict):
+        """
+        Invokes the new AirPollution API history endpoint
+
+        :param params_dict: dict of parameters
+        :returns: a string containing raw JSON data
+        :raises: *ValueError*, *APIRequestError*
+
+        """
+        _, json_data = self._client.get_json(AIR_POLLUTION_HISTORY_URL, params=params_dict)
+        return json_data
+
     def __repr__(self):
         return "<%s.%s - httpclient=%s>" % \
                (__name__, self.__class__.__name__, str(self._client))

pyowm/airpollutionapi30/airpollution_manager.py

@@ -5,7 +5,7 @@
 from pyowm.airpollutionapi30.uris import ROOT_POLLUTION_API_URL, NEW_ROOT_POLLUTION_API_URL
 from pyowm.commons.http_client import HttpClient
 from pyowm.constants import AIRPOLLUTION_API_VERSION
-from pyowm.utils import geo, decorators
+from pyowm.utils import geo, decorators, formatting, timestamps
 
 
 class AirPollutionManager:
@@ -239,5 +239,42 @@ def air_quality_forecast_at_coords(self, lat, lon):
         except:
             return []
 
+    def air_quality_history_at_coords(self, lat, lon, start, end=None):
+        """
+        Queries the OWM AirPollution API for available forecasted air quality indicators around the specified coordinates.
+
+        :param lat: the location's latitude, must be between -90.0 and 90.0
+        :type lat: int/float
+        :param lon: the location's longitude, must be between -180.0 and 180.0
+        :type lon: int/float
+        :param start: the object conveying the start value of the search time window
+        :type start: int, ``datetime.datetime`` or ISO8601-formatted string
+        :param end: the object conveying the end value of the search time window. Values in the future will be clipped
+           to the current timestamp. Defaults to the current UNIX timestamp.
+        :type end: int, ``datetime.datetime`` or ISO8601-formatted string
+        :return: a `list` of *AirStatus* instances or an empty `list` if data is not available
+        :raises: *ParseResponseException* when OWM AirPollution API responses' data
+            cannot be parsed, *APICallException* when OWM AirPollution API can not be
+            reached, *ValueError* for wrong input values
+        """
+        geo.assert_is_lon(lon)
+        geo.assert_is_lat(lat)
+        now = timestamps.now(timeformat='unix')
+        assert start is not None
+        start = formatting.timeformat(start, 'unix')
+        if end is None:
+            end = now
+        else:
+            end = formatting.timeformat(end, 'unix')
+            if end > now:
+                end = now
+
+        params = {'lon': lon, 'lat': lat, 'start': start, 'end': end}
+        json_data = self.new_ap_client.get_historical_air_pollution(params)
+        try:
+            return airstatus.AirStatus.from_dict(json_data)
+        except:
+            return []
+
     def __repr__(self):
         return '<%s.%s>' % (__name__, self.__class__.__name__)

pyowm/airpollutionapi30/uris.py

@@ -13,3 +13,4 @@
 NEW_ROOT_POLLUTION_API_URL = 'openweathermap.org/data/2.5'
 AIR_POLLUTION_URL = 'air_pollution'
 AIR_POLLUTION_FORECAST_URL = 'air_pollution/forecast'
+AIR_POLLUTION_HISTORY_URL = 'air_pollution/history'

sphinx/v3/code-recipes.md

@@ -878,6 +878,36 @@ for air_status in list_of_forecasts:
     air_status.aqi  # air quality index
 ```
 
+### Getting historical air pollution data on geographic coords 
+We can get also get historical values for air pollution agents concentration and air quality index:
+
+```python
+from pyowm.owm import OWM
+owm = OWM('your-api-key')
+mgr = owm.airpollution_manager()
+
+# fetch history from a certain point in time up to now...
+start = 1606223802  # November 24, 2020
+list_of_historical_values = mgr.air_quality_history_at_coords(51.507351, -0.127758, start)  # London, GB
+
+# ...or fetch history on a closed timeframe in the past
+end = 1613864065  # February 20, 2021
+list_of_historical_values = mgr.air_quality_history_at_coords(51.507351, -0.127758, start, end=end)  # London, GB
+
+# Each item in the list_of_historical_values is an AirStatus object 
+for air_status in list_of_historical_values:
+    air_status.co
+    air_status.no
+    air_status.no2
+    air_status.o3
+    air_status.so2
+    air_status.pm2_5
+    air_status.pm10
+    air_status.nh3
+    air_status.aqi  # air quality index
+```
+
+
 
 <div id="station_measurements"/>
 

tests/integration/airpollutionapi30/test_integration_pollutionapi30.py

@@ -33,6 +33,20 @@ def test_air_quality_forecast_at_coords(self):
             self.assertIsNotNone(airstatus.reference_time())
             self.assertIsNotNone(airstatus.location)
 
+    def test_air_quality_history_at_coords(self):
+        """
+        Test feature: get historical air quality data around geo-coordinates.
+        """
+        start = 1606223802  # Tuesday, November 24, 2020
+
+        list_of_airstatuses = self.__owm.air_quality_history_at_coords(45, 9, start)
+        self.assertIsInstance(list_of_airstatuses, list)
+        for airstatus in list_of_airstatuses:
+            self.assertIsNotNone(airstatus.air_quality_data)
+            self.assertIsNotNone(airstatus.reception_time())
+            self.assertIsNotNone(airstatus.reference_time())
+            self.assertIsNotNone(airstatus.location)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/airpollutionapi30/test_airpollution_manager.py

@@ -6,6 +6,7 @@
 from pyowm.airpollutionapi30 import airpollution_client, airpollution_manager, coindex, so2index, ozone, no2index, airstatus
 from pyowm.config import DEFAULT_CONFIG
 from pyowm.constants import AIRPOLLUTION_API_VERSION
+from pyowm.utils import timestamps
 from tests.unit.airpollutionapi30.test_ozone import OZONE_JSON
 from tests.unit.airpollutionapi30.test_coindex import COINDEX_JSON
 from tests.unit.airpollutionapi30.test_no2index import NO2INDEX_JSON
@@ -32,6 +33,9 @@ def mock_get_air_pollution(self, params_dict):
     def mock_get_forecast_air_pollution(self, params_dict):
         return json.loads(AIRSTATUS_MULTIPLE_JSON)
 
+    def mock_get_historical_air_pollution(self, params_dict):
+        return json.loads(AIRSTATUS_MULTIPLE_JSON)
+
     def mock_get_so2_returning_so2index_around_coords(self, params_dict):
         return json.loads(SO2INDEX_JSON)
 
@@ -229,5 +233,46 @@ def test_air_quality_forecast_at_coords_fails_with_wrong_parameters(self):
         self.assertRaises(ValueError, airpollution_manager.AirPollutionManager.air_quality_forecast_at_coords, \
                           self.__test_instance, 200, 2.5)
 
+    def test_air_quality_history_at_coords(self):
+        ref_to_original = airpollution_client.AirPollutionHttpClient.get_historical_air_pollution
+        airpollution_client.AirPollutionHttpClient.get_historical_air_pollution = \
+            self.mock_get_historical_air_pollution
+        result = self.__test_instance.air_quality_history_at_coords(45, 9, 12345678)
+        airpollution_client.AirPollutionHttpClient.get_historical_air_pollution = ref_to_original
+        self.assertTrue(isinstance(result, list))
+        for item in result:
+            self.assertIsInstance(item, airstatus.AirStatus)
+            self.assertIsNotNone(item.reference_time)
+            self.assertIsNotNone(item.reception_time())
+            loc = item.location
+            self.assertIsNotNone(loc)
+            self.assertIsNotNone(loc.lat)
+            self.assertIsNotNone(loc.lon)
+            self.assertIsNotNone(item.air_quality_data)
+
+    def test_air_quality_history_at_coords_fails_with_wrong_parameters(self):
+        self.assertRaises(ValueError, airpollution_manager.AirPollutionManager.air_quality_history_at_coords, \
+                          self.__test_instance, 43.7, -200.0, 12345678, 12349999)
+        self.assertRaises(ValueError, airpollution_manager.AirPollutionManager.air_quality_history_at_coords, \
+                          self.__test_instance, 43.7, 200.0, 12345678, 12349999)
+        self.assertRaises(ValueError, airpollution_manager.AirPollutionManager.air_quality_history_at_coords, \
+                          self.__test_instance, -200, 2.5, 12345678, 12349999)
+        self.assertRaises(ValueError, airpollution_manager.AirPollutionManager.air_quality_history_at_coords, \
+                          self.__test_instance, 200, 2.5, 12345678, 12349999)
+        self.assertRaises(ValueError, airpollution_manager.AirPollutionManager.air_quality_history_at_coords, \
+                          self.__test_instance, 200, 2.5, 'test')
+        self.assertRaises(ValueError, airpollution_manager.AirPollutionManager.air_quality_history_at_coords, \
+                          self.__test_instance, 200, 2.5, 'test', 'test2')
+
+    def test_air_quality_history_at_coords_clips_end_param_to_current_timestamp(self):
+        now = timestamps.now(timeformat='unix')
+        end = now + 99999999999
+
+        def assert_clipped(obj, params_dict):
+            self.assertEqual(params_dict['end'], now)
+
+        airpollution_client.AirPollutionHttpClient.get_historical_air_pollution = assert_clipped
+        _ = self.__test_instance.air_quality_history_at_coords(45, 9, 12345678, end=end)
+
     def test_repr(self):
         print(self.__test_instance)