Download, manage and plot weather data from Darksky / OpenWeatherMap APIs
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.
pip install weatho
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).
The following methods are available from a
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
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.
Date/time and timezone information
It is preferable to use timezone-aware datetimes when specifying dates to the
In particular, when calling
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 (
- 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.
current()etc.), localize to whatever timezone is more convenient to work with (if using naïve, local time of the computer will be used).
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
For tests, the module
weatho.locationsstores coordinates of some cities/locations as a
- Python >= 3.6
(installed automatically by pip if necessary)
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.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.