PyOWM

A Python wrapper around the OpenWeatherMap API

What is it?

PyOWM is a client Python wrapper library for the OpenWeatherMap (OWM) web API.

It allows quick and easy consumption of OWM weather data from Python applications via a simple object model and in a human-friendly fashion.

No additional libraries are requested: only the Python standard library modules.

Support

PyOWM currently supports version 2.5 of the OWM API

PyOWM runs on Python 2.7, 3.2, 3.3, 3.4 and 3.5

Usage

API key

As the OpenWeatherMap API needs a valid API key to allow responses, PyOWM won't work if you don't provide one. This stands for both the free and paid (pro) subscription plans.

You can signup for a free API key on the OWM website

Please notice that the free API subscription plan is subject to requests throttling.

Examples

import pyowm

owm = pyowm.OWM('your-API-key')  # You MUST provide a valid API key

# You have a pro subscription? Use:
# owm = pyowm.OWM(API_key='your-API-key', subscription_type='pro')
    
# Will it be sunny tomorrow at this time in Milan (Italy) ?
forecast = owm.daily_forecast("Milan,it")
tomorrow = pyowm.timeutils.tomorrow()
forecast.will_be_sunny_at(tomorrow)  # Always True in Italy, right? ;-)

# Search for current weather in London (UK)
observation = owm.weather_at_place('London,uk')
w = observation.get_weather()
print(w)                      # <Weather - reference time=2013-12-18 09:20, 
                              # status=Clouds>

# Weather details
w.get_wind()                  # {'speed': 4.6, 'deg': 330}
w.get_humidity()              # 87
w.get_temperature('celsius')  # {'temp_max': 10.5, 'temp': 9.7, 'temp_min': 9.0}

# Search current weather observations in the surroundings of 
# lat=22.57W, lon=43.12S (Rio de Janeiro, BR)
observation_list = owm.weather_around_coords(-22.57, -43.12)

Installation

Using pip

pip install pyowm

From source with setuptools

Download the source archive either from GitHub (select a release or just take the main branch) or from the Python Package Index
Uncompress:
```
`unzip pywom-x.y.z`
```

Launch setuptools:

`cd pywom-x.y.z`

`python setup.py install`

exe installer (Windows users)

The installer is available on the Python Package Index

Docker

You can run a Docker container mounting the latest PyOWM release code with:

docker run -d --name pyowm csparpa/pyowm

The source code is under /pyowm inside the container. You can globally install PyOWM on the container with:

docker exec -ti pyowm bash -c 'pip install pyowm'

License

MIT license

Changelog

Please read the changelog page of the wiki

Documentation

Usage examples are available in the wiki page.

The library API documentation is available on Read the Docs.

Testing

Run tests using Tox. From the project root folder, just launch:

tox

Also, unit tests can be run with: pythonX.Y setup.py test -s tests.unit.

PyOWM is continuously built with Travis-CI and code coverage is checked with Coveralls.io

Discussion

Join the PyOWM public Slack team by signing up here

Development

Contributors (code enhancement, issue/bug reporting) are welcome!. See the notes on development to get started.

Since version 2.2 PyOWM adopts Semantic Versioning.

If you liked PyOWM, consider giving me a tip!

alechewitt/pyowm