weatho 1.0.1

Download, manage and plot weather data from Darksky / OpenWeatherMap APIs

About

Access, download and plot weather data from the following APIs:

• Darksky (https://darksky.net/dev)
• OpenWeatherMap (https://openweathermap.org/api)

Both sources require an API key to get access to the data. However, when dealing with data already downloaded as files and stored locally, the API key is not necessary.

Install

pip install weatho

Quick Start

from weatho import Weather, plot

# source can be 'owm' or 'darksky'
w = Weather(location=(45.77, 4.84), source='owm', api_key='xyz')

# Get raw data from the API (source-dependent)
# --------------------------------------------

w.url()    # get URL at which to downlowd data
w.fetch()  # get data as a dictionary

# By default, current data; get historical data by passing a datetime.datetime:

from datetime import datetime, timedelta
from pytz import timezone
tz = timezone('Europe/Paris')
date = tz.localize(datetime(2021, 1, 15, 12))  # 15 Jan. 2021 at Noon in Paris timezone

w.url(date)
w.fetch(date)

# Get and plot formatted, source-independent data
# -----------------------------------------------

w.current()   # current weather conditions
w.hourly()    # hourly data for present day, including forecast

# It is also possible to access historical data:
w.current(date)
w.hourly(date, until=date + timedelta(days=3))

# Plot hourly data:
plot(w.hourly())

There are also options to download the data directly as .json files in a folder and work from this data (see below).

For detailed examples, see the Examples.ipynb notebook (https://github.com/ovinc/weatho/blob/master/Examples.ipynb).

Contents

Weather class

The following methods are available from a Weather object:

• For raw, source-dependent data:

  • url() and copy-paste the link into a browser (returns url link)
  • fetch() to get the raw data from the internet (returns dict of data)
  • save() to save the raw data into a .json file
  • load() to get the raw data from a .json file (returns dict of data)

• For formatted, source-independent data for analysis and plotting:

  • current(): returns a dict of values (data at specific time)
  • hourly(): returns a dict of lists of values (hourly data), can be used in plot() directly.

• To download data from the API into local files, possibly in batch:

  • download(): saves API data in .json format in a folder (threaded for multiple requests at the same time).
  • missing_days(): checks if there are any missing files of data between specified dates in a folder.
  • download_missing_days(): same as above, but also downloads the missing data in the folder.

Note: To access data from downloaded files, use load() to get raw data, and hourly(path=...) to get formatted data.

Plotting weather data

• plot(): takes formatted hourly data from hourly() (either using the API or downloaded files) as input.

Notes

Date/time and timezone information

• It is preferable to use timezone-aware datetimes when specifying dates to the Weather methods.

• In particular, when calling download() or hourly(), care must be taken because DarkSky and OpenWeatherMap do not manage hourly data the same way:

  • DarkSky generates hourly data from 00:00 to 23:59 in local time (of the requested location)
  • OpenWeatherMap uses 00:00 to 23:59 in UTC time

This means that with OpenWeatherMap, calling hourly() with a datetime(2021, 1, 15) localized in Central European Time will return data from 14/01/2021, 1:00 to 15/01/2021 00:00 (included) in local time, while doing the same thing with DarkSky will return data from 15/01/2021, 0:00 to 15/01/2021 23:00 (included) in local time.

Data stored in .json files using download() follows this pattern. For example:

• OWM_45.77,4.84,2021-01-15.json: data from 00:00 to 23:00 (included) on 15 Jan. 2021, UTC Time
• DarkSky_45.77,4.84,2021-01-15.json: data from 00:00 to 23:00 (included) on 15 Jan. 2021, local Time (of the requested location)

In conclusion, to avoid problems with hourly data (hourly(), download(), etc.):

• with DarkSky, localize all datetimes to the local timezone of the place you're requesting weather for,
• with OpenWeatherMap, work with UTC timezone.
• for other calls (e.g. fetch(), current() etc.), localize to whatever timezone is more convenient to work with (if using naïve, local time of the computer will be used).

Misc.

• If one gets the error KeyError: 'hourly', it's likely that the data is not downloaded correctly or inexistent. Check that the API key is correct and/or test the download URL generated by url() in a browser.

• More data might be available compared to the ones in formatted data, see e.g. the raw dictionary returned by functions like fetch() or load().

• For tests, the module weatho.locations stores coordinates of some cities/locations as a coordinates dictionary.

Other information

Python requirements

• Python >= 3.6

Package requirements

(installed automatically by pip if necessary)

• requests
• matplotlib
• pytz
• importlib_metadata

Author

Olivier Vincent

([e-mail])

License

BSD 3-Clause (see LICENSE file)

BSD 3-Clause License

Copyright (c) 2020, Olivier VINCENT All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.