PyOWM¶
Welcome to PyOWM v3 documentation!
What is PyOWM?¶
PyOWM is a client Python wrapper library for OpenWeatherMap web APIs. It allows quick and easy consumption of OWM data from Python applications via a simple object model and in a human-friendly fashion.
What APIs can I access with PyOWM?¶
With PyOWM you can interact programmatically with the following OpenWeatherMap web APIs:
- Weather API v2.5 + OneCall API, offering
- current weather data
- weather forecasts
- weather history
- Agro API v1.0, offering polygon editing, soil data, satellite imagery search and download
- Air Pollution API v3.0, offering data about CO, O3, NO2 and SO2
- UV Index API v3.0, offering data about Ultraviolet exposition
- Stations API v3.0, allowing to create and manage meteostation and publish local weather measurements
- Weather Alerts API v3.0, allowing to set triggers on weather conditions and areas and poll for spawned alerts
- Geocoding API v1.0 allowing to perform direct/reverse geocoding
And you can also get image tiles for several map layers provided by OWM
The documentation of OWM APIs can be found on the OWM Website
Very important news¶
OpenWeatherMap API recently “blocked” calls towards a few legacy API endpoints whenever requested by clients using non-recent free API keys.
This means that if you use PyOWM methods such as the ones for getting observed or forecasted weather, PyOWM might return authorization errors This behaviour is not showing if you use API keys issued a long time ago.
The proper way to obtain such data is to call the “OneCall” methods using your API key
Used to work with PyOWM v2?¶
PyOWM v3 is a brand new branch of the library and therefore differs from PyOWM v2 branch. This means that v3 offers no retrocompatibility with v2: this might result in your code breaking if it uses PyOWM v2 and you uncarefully update! Moreover, PyOWM v3 runs on Python 3 only.
PyOWM v2 will follow this Timeline
It is highly recommended that you upgrade your PyOWM v2 dependency to PyOWM v3: follow this guide for Migrating
Supported environments and Python versions¶
PyOWM runs on Windows, Linux and MacOS. PyOWM runs on Python 3.7+
Usage and Technical Documentation¶
PyOWM v3 documentation¶
Quick code recipes¶
FAQ about common errors¶
Description of PyOWM configuration¶
Global PyOWM instantiation documentation¶
City ID registry documentation¶
Weather API examples¶
Agro API examples¶
UV API examples¶
Air Pollution API examples¶
Stations API examples¶
Alerts API examples¶
Geocoding API examples¶
Map tiles client examples¶
PyOWM Exceptions¶
Utility functions examples¶
Legacy PyOWM v2 documentation¶
Please refer to historical archives on Readthedocs or the GitHub repo for this
Installation¶
pip¶
The easiest method of all:
$ pip install pyowm
If you already have PyOWM 2.x installed and want to upgrade to safely update it to the latest 2.x release just run:
$ pip install --upgrade pyowm>=2.0,<3.0
Get the latest development version¶
You can install the development trunk with _pip_:
git clone https://github.com/csparpa/pyowm.git
cd pyowm && git checkout develop
pip install -r requirements.txt # install dependencies
python setup.py install # install develop branch code
but be aware that it might not be stable!
setuptools¶
You can install from source using _setuptools_: either download a release from GitHub or just take the latest main branch), then:
$ unzip <zip archive> # or tar -xzf <tar.gz archive>
$ cd pyowm-x.y.z
$ python setup.py install
The .egg will be installed into the system-dependent Python libraries folder
Distribution packages¶
On Windows you have EXE installers
On ArchLinux you can use the Yaourt package manager, run:
Yaourt -S python2-owm # Python 2.7 (https://aur.archlinux.org/packages/python-owm)
Yaourt -S python-owm # Python 3.x (https://aur.archlinux.org/packages/python2-owm)
On OpenSuse you can use with YaST/Zypper package manager, run:
zypper install python-pyowm
How to contribute¶
There are multiple ways to contribute to the PyOWM project! Find the one that suits you best
