improved

Author: csparpa

sphinx/v3/code-recipes.md

@@ -666,9 +666,15 @@ The `raw_measurements_dict` contains multiple sub-dicts, each one being a a data
 
 With the OneCall Api you can get the current weather, hourly forecast for the next 48 hours and the daily forecast for the next seven days in one call.
 
-Below some examples:
+One Call objects can be thought of as datasets that "photograhp" of observed and forecasted weather data for a location: such photos are given for a specific timestamp.
 
-### What is the feels like temperature (°C) tomorrow morning?
+It is possible to get:
+  - current OneCall data: the "photo" given for today)
+  - historical OneCall data: "photos" given for past days, up to 5 
+
+### Current OneCall data
+
+#### What is the feels like temperature (°C) tomorrow morning?
 Always in Berlin:
 
 ```python
@@ -680,7 +686,7 @@ one_call = mgr.one_call(lat=52.5244, lon=13.4105)
 one_call.forecast_daily[0].temperature('celsius').get('feels_like_morn', None) #Ex.: 7.7
 ```
 
-### What's the wind speed in three hours?
+#### What's the wind speed in three hours?
 
 __Attention: The first entry in forecast_hourly is the current hour.__
 If you send the request at 18:36 UTC then the first entry in forecast_hourly is from 18:00 UTC.
@@ -696,7 +702,7 @@ one_call = mgr.one_call(lat=52.5244, lon=13.4105)
 one_call.forecast_hourly[3].wind().get('speed', 0) # Eg.: 4.42
 ```
 
-### What's the current humidity?
+#### What's the current humidity?
 
 Always in Berlin:
 
@@ -708,3 +714,54 @@ one_call = mgr.one_call(lat=52.5244, lon=13.4105)
 
 one_call.current.humidity # Eg.: 81
 ```
+
+### Historical OneCall data
+
+Remember the "photograph" metaphor for OneCall data. You can query for "photos" given for past days: when you do that,
+be aware that such a photo carries along weather forecasts (hourly and daily) that *might* refer to the past
+
+This is because - as said above - the One Call API returns hourly forecasts for a streak of 48 hours and daily forecast 
+for a streak of 7 days, both streaks beginning from the timestamp which the OneCall object refers to
+
+In case of doubt, anyway, you can always _check the reference timestamp_ for the `Weather` objects embedded into the
+OneCall object and check if it's in the past or not.
+
+
+#### What was the observed weather yesterday at this time?
+
+Always in Berlin: 
+
+```python
+from pyowm.owm import OWM
+from pyowm.utils import timestamps, formatting
+
+owm = OWM('your-api-key')
+mgr = owm.weather_manager()
+
+# what is the epoch for yesterday at this time?
+yesterday_epoch = formatting.to_UNIXtime(timestamps.yesterday())
+
+one_call_yesterday = mgr.one_call_history(lat=52.5244, lon=13.4105, dt=yesterday_epoch)
+
+observed_weather = one_call_yesterday.current
+```
+
+#### What was the weather forecasted 3 days ago for the subsequent 48 hours ?
+
+No way we move from Berlin:
+
+```python
+from pyowm.owm import OWM
+from pyowm.utils import timestamps
+from datetime import datetime, timedelta, timezone
+
+owm = OWM('your-api-key')
+mgr = owm.weather_manager()
+
+# what is the epoch for 3 days ago at this time?
+three_days_ago_epoch = int((datetime.now() - timedelta(days=3)).replace(tzinfo=timezone.utc).timestamp())
+
+one_call_three_days_ago = mgr.one_call_history(lat=52.5244, lon=13.4105, dt=three_days_ago_epoch)
+
+list_of_forecasted_weathers = one_call_three_days_ago.forecast_hourly
+```