Openweathermapy
Python package wrapping OpenWeatherMap.org's API 2.5.
Overview
As OpenWeatherMap.org returns data mostly in the form of nested dictionaries, Openweathermapy gives a simple API to access items in a comfortable way:
# classic access
item = data["main"]["temp"]
# openweathermapy access
item = data("main.temp")
# access multiple items at once
>>> items = data("main.temp", "wind.speed")
Status
Development Beta
Version
0.7.0
Changelog
- 2015-08-09 optional
pandas.DataFrame
support added for forecast and historical data
Requirements
Openweathermapy supports Python 2.7, 3.2, 3.3 and 3.4. There are no more requirements,
but for forecast and historical data pandas.DataFrame
objects can be returned.
So it is cool to install Pandas as well but it is not madatory.
Installation
# via pip
~$ pip install openweathermapy
# or download package and run ...
~$ python setup.py install
Getting started
>>> import openweathermapy.core as owm
All parameters defined in OpenWeatherMap.org's API documentation can be passed to the functions
in Openweathermapy as keyword arguments **params
.
The query string always depends on the request (API call), but unsupported parameters will not raise an error.
Most common ones to be used are units
, lang
and (if needed) APPID
. So it may be a good idea to pass them
in the form of a settings dictionary:
>>> settings = {"units": "metric", "lang": "DE"}
>>> data = owm.get_current("Kassel,DE", **settings)
# settings containing APIKEY
>>> settings = {"APPID": 1111111111, "units": "metric"}
Data objects
The main data object is openweathermapy.utils.NestedDict
, which extends Python's builtin dict
by methods giving a more flexible access to the items as shown above. If a list of weather data (objects) is returned
openweathermapy.utils.NestedDictList
or openweathermapy.core.DataBlock
is used. The latter one just adds
an attribute meta
to the NestedDictList
containing the meta data of the responses:
# get current weather data (data point)
>>> data = owm.get_current("Kassel,DE")
>>> type(data)
openweathermapy.utils.NestedDict
# get forecast data (data block)
>>> data = owm.get_forecast_daily("London,UK")
>>> type(data)
openweathermapy.core.DataBlock
>>>type(data.meta)
openweathermapy.utils.NestedDict
Views
A view is just a list of keys to extract data from the responses. So, you can define views like summary, minimal etc. depending on your needs. This keeps everything as flexible as possible:
>>> views = {
... "summary": ["main.temp", "main.pressure", "main.humidity"]
... }
>>> data = owm.get_current("London,UK", units="metric")
>>> data(*views["summary"])
(18.56, 1011, 63)
# return complete keys
>>> data.get_dict(views["summary"])
{'main.temp': 18.56, 'main.humidity': 63, 'main.pressure': 1011}
# return only last key
>>> data.get_dict(views["summary"], split_keys=True)
{'pressure': 1011, 'temp': 18.56, 'humidity': 63}
You can also load views from files in json format for example by using openweathermapy.utils.load_config
.
Fetch current weather data
The city
argument can be given as name, id, or geographic coordinates.
If you want to stay as close as possible to the original API, you can also skip the
first argument and use the parameters q
, id
, lat
and lon
or zip
instead,
for details see OpenWeatherMap.org's API documentation:
# get data by city name and country code
>>> data = owm.get_current("Kassel,DE")
# get data by city id and set language to german (DE)
>>> data = owm.get_current(2892518, lang="DE")
# get data by latitude and longitude and return temperatures in Celcius
>>> location = (51.32, 9.5)
>>> data = owm.get_current(location, units="metric")
# optional: skip city argument and get data by zip code
>>> data = owm.get_current(zip="34128,DE")
# access single item
>>> data("main.temp")
11.06
# access multiple items at once
>>> keys = ["main.temp", "main.humidity", "wind.speed"]
>>> data.get_many(keys)
(11.06, 58, 6.2)
# alternative access
>>> data(*keys)
(11.06, 58, 6.2)
# get data for 'Kassel,DE', 'Malaga,ES', 'New York,US'
>>> city_ids = (2892518, 2514256, 5128581)
>>> data = owm.get_current_for_group(city_ids, units="metric", lang="DE")
>>> data_malaga = data[1]
# find city by name and return data for match(es)
>>> data = owm.find_city("Malaga")
# get data for 5 cities around geographic coordinates
>>> location = (51.32, 9.5)
>>> data = owm.find_cities_by_geo_coord(location, 5)
# get data from station
>>> data = owm.get_current_from_station(4926)
# get stations by geographic coordinates
>>> location = (51.32, 9.5)
>>> data = owm.find_stations_by_geo_coord(location)
Fetch forecast data
The city
argument can be given in the same way as shown in the examples above.
# get 3h forecast data
>>> data = owm.get_forecast_hourly("Kassel,DE", lang="DE")
# get daily forecast data for 7 days
>>> data = owm.get_forecast_daily("Kassel,DE", 7, units="metric")
# show meta data
>>> data.meta
{u'city': {u'country': u'DE', u'population': 0, u'id': 2892518,
u'coord': {u'lat': 51.316669, u'lon': 9.5}, u'name': u'Kassel'},
u'message': 0.0185, u'cod': u'200', u'cnt': 7}
# get coordinates and id
>>> data.meta("city.coord", "city.id")
({u'lat': 51.316669, u'lon': 9.5}, 2892518)
# select columns
>>> selection = data.select(["dt", "temp.min", "temp.max"])
>>> for line in selection:
... line
...
(1437044400, 16.63, 24.99)
(1437130800, 18.21, 30.17)
(1437217200, 14.96, 26.35)
(1437303600, 15.82, 23.49)
(1437390000, 15.52, 23.95)
(1437476400, 18.77, 29.11)
(1437562800, 14.67, 27.11)
# convert column "dt" to datetime string
>>> from datetime import datetime as dt
>>> conv = {"dt": lambda ts: str(dt.utcfromtimestamp(ts))}
>>> selection = data.select(["dt", "temp.min", "temp.max"], converters=conv)
>>> for line in selection:
... line
...
('2015-07-16 11:00:00', 16.63, 24.99)
('2015-07-17 11:00:00', 18.21, 30.17)
('2015-07-18 11:00:00', 14.96, 26.35)
('2015-07-19 11:00:00', 15.82, 23.49)
('2015-07-20 11:00:00', 15.52, 23.95)
('2015-07-21 11:00:00', 18.77, 29.11)
('2015-07-22 11:00:00', 14.67, 27.11)
Fetch historical data
For a complete list of parameters, which can be passed, please refer to OpenWeatherMap.org's API documention.
# get historical data by city name
>>> data = owm.get_history("Kassel,DE")
# define time period
>>> from datetime import datetime as dt
>>> date_s = dt(2015, 4, 1).timestamp()
>>> date_e = dt(2015, 4, 6).timestamp()
# get historical data for given time period by city id
>>> data = owm.get_history(2892518, start=date_s, end=date_e)
# give start date and number of hours to be retured
>>> data = owm.get_history("London,UK", start=date_s, cnt=48)
# get historical data from station
>>> data = owm.get_history_from_station(4926)
Pandas support
Since Openweathermapy version 0.7.0
For forecast and historical data it is possible to get pandas.DataFrame
objects from the responses:
>>> data = owm.get_forecast_daily("London,UK")
# keys will be used as column names
>>> selection = data.select_pandas(["dt", "main.temp", "wind.speed"])
>>> selection.set_index("dt")
# it is also possible to pass an index column to the function
>>> dates = data.get("dt")
>>> selection = data.select_pandas(["main.temp", "wind.speed"], index=dates)
>>> selection.to_csv()