PyOWM utility functions usage example¶

PyOWM provides a few packages that contain utility functions.

Some of them are specifically designed to be used by the core PyOWM classes but others you can use to make your life easier when operating PyOWM!

All utility modules live inside the pyowm.utils package

Here are most useful modules:

config: handling of PyOWM configuration
formatting: formatting of timestamp entities (Python native types, UNIX epochs and ISO-8601 strings)
geo: handling of geographic entities such as points, polygons and their geoJSON representation
measureables: conversions among physical units (eg. temperature, wind)
timestamps: human friendly timestamps generation

`config` module¶

from pyowm.utils.config import get_default_config, get_default_config_for_subscription_type, \ 
    get_default_config_for_proxy, get_config_from 

config_dict = get_default_config()                                       # loads the default config dict
config_dict = get_default_config_for_subscription_type('professional')   # loads the config dict for the specified subscription type
config_dict = get_config_from('/path/to/configfile.json')                # loads the config dict from the  specified JSON file
config_dict = get_default_config_for_proxy('http_url', 'https_url')      # loads the config dict to be used behind a proxy whose URLs are specified

`formatting` module¶

from datetime import datetime as dt
from pyowm.utils import formatting

unix_value = formatting.timeformat(dt.today(), 'unix')        # from datetime to UNIX
iso_str_value = formatting.timeformat(dt.today(), 'iso')      # from datetime to ISO-8601 string
datetime_value = formatting.timeformat(1590100263, 'date')    # from UNIX to datetime
iso_str_value = formatting.timeformat(1590100263, 'iso')      # from UNIX to ISO-8601 string
datetime_value = formatting.timeformat('2020-05-21 22:31:03+00:00', 'date') # from ISO-8601 string to datetime
unix_value = formatting.timeformat('2020-05-21 22:31:03+00:00', 'unix') # from ISO-8601 string to UNIX

`geo` module¶

The module provides classes to represent geometry features:

Point
Multipoint (aka point set)
Polygon
Multipolygon (aka polygon set)

Geometry features are used eg. in OWM Alert API to provide geographical boundaries for alert setting.

PyOWM uses standard geometry types defined by the GeoJSON Format Specification - RFC 7946 data interchange format.

Common geometry methods¶

All geometry types can be dumped to a GeoJSON string and to a Python dict

from pyowm.utils import geo
point = geo.Point(20.8, 30.9)
point.geojson()  # '{"type": "Point", "coordinates": [20.8, 30.9]}'
point.to_dict()  #  {'type': 'Point', 'coordinates': [20.8, 30.9]}

All geometry types also feature a static factory method: you provide the dictionary and the factory returns the object instance

from pyowm.utils.geo import Point
point_dict = {'type': 'Point', 'coordinates': [20.8, 30.9]}
point = Point.from_dict(point_dict)

Please refer to the GeoJSON specification about how to properly format the dictionaries to be given the factory methods

`Point` class¶

A point is a couple of geographic coordinates: longitude and latitude

from pyowm.utils import geo
lon = 20.8
lat = 30.9
point = geo.Point(lon, lat)
coords = point.lon, point.lat  # 20.8, 30.9 

As circle shapes are not part of the GeoJSON specification, you can approximate the circle having a specific Point instance at its center with a square polygon: we call it bounding square polygon. You just need to provide the radius of the circle you want to approximate (in kms):

from pyowm.utils import geo
point = geo.Point(20.8, 30.9)
polygon = point.bounding_square_polygon(inscribed_circle_radius_km=2.0)   # default radius: 10 km

Please, notice that if you specify big values for the radius you need to take care about the projection of geographic coordinates on a proper geoid: this means that if you don’t, the polygon will only approximate a square.

From City IDs to `Point` objects¶

The City ID Registry class can return the geopoints that correspond to one or more named cities:

import pyowm
owm = pyowm.OWM('your-API-key')
reg = owm.city_id_registry()
list_of_geopoints = reg.geopoints_for('London', country='GB')

This, in combination with the bounding_square_polygon method, makes it possible to easily get polygons to cover large squared areas centered on largely spread city areas - such as London,GB itself:

london_city_centre = geopoints[0]
london_city_bounding_polygon = london_city_centre.bounding_square_polygon(inscribed_circle_radius_km=12)

`MultiPoint` class¶

A MultiPoint object represent a set of Point objects

from pyowm.utils.geo import Point, MultiPoint
point_1 = Point(20.8, 30.9)
point_2 = Point(1.2, 0.4)

# many ways to instantiate
multipoint = MultiPoint.from_points([point_1, point_2])
multipoint = MultiPoint([20.8, 30.9], [1.2, 0.4])

multipoint.longitudes  # [20.8, 1.2]
multipoint.latitudes   # [30.9, 0.4]

`Polygon` class¶

A Polygon object represents a shape made by a set of geopoints, connected by lines. Polygons are allowed to have “holes”. Each line of a polygon must be closed upon itself: this means that the last geopoint defined for the line must coincide with its first one.

from pyowm.utils.geo import Polygon, Point
point_1_coords = [2.3, 57.32]
point_2_coords = [23.19, -20.2]
point_3_coords = [-120.4, 19.15]
point_1 = Point(point_1_coords)
point_2 = Point(point_2_coords)
point_3 = Point(point_3_coords)


# many ways to instantiate
line = [point_1_coords, point_2_coords, point_3_coords , point_1_coords]  # last point equals the first point
polygon = Polygon([line])
line = [point_1, point_2, point_3, point_1]  # last point equals the first point
polygon = Polygon.from_points([line])

`MultiPolygon` class¶

A MultiPolygon object represent a set of Polygon objects Same philosophy here as for MultiPoint class, polygons can cross:

from pyowm.utils.geo import Point, Polygon, MultiPolygon
point_1 = Point(20.8, 30.9)
point_2 = Point(1.2, 0.4)
point_3 = Point(49.9, 17.4)
point_4 = Point(178.4, 78.3)
polygon_1 = Polygon.from_points([point_1, point_2, point_3, point_1])
polygon_2 = Polygon.from_points([point_3, point_4, point_2, point_3])

multipoint = MultiPolygon.from_polygons([polygon_1, polygon_2])

Building geometries¶

There is a useful factory method for geometry types, which you can use to turn a geoJSON-formatted dictionary into the corresponding topology type:

from pyowm.utils.geo import GeometryBuilder
point_dict = {
    "type": "Point",
    "coordinates": [53, 37]
}
point = GeometryBuilder.build(point_dict)      # this is a `Point` instance

wrongly_formatted_dict = {"a": 1, "b": 99}
GeometryBuilder.build(wrongly_formatted_dict)  # you get an exception

`measurables` module¶

This module provides utilities numeric conversions

Temperature¶

You have a dict whose values represent temperature units in Kelvin: you can convert them to Fahrenheit and Celsius.

from pyowm.utils import measurables

fahrenheit_temperature_dict = measurables.kelvin_dict_to(kelvin_temperature_dict, 'fahrenheit')
celsius_temperature_dict = measurables.kelvin_dict_to(kelvin_temperature_dict, 'celsius')

Wind¶

On the same line as temperatures, you can convert wind values among meters/sec, kilometers/hour, miles/hour, knots and the Beaufort scale. The pivot unit of measure for wind is meters/sec

from pyowm.utils import measurables

kmhour_wind_dict = measurables.metric_wind_dict_to_km_h(msec_wind_dict)
mileshour_wind_dict = measurables.metric_wind_dict_to_imperial(msec_wind_dict)
knots_wind_dict = measurables.metric_wind_dict_to_knots(msec_wind_dict)
beaufort_wind_dict = measurables.metric_wind_dict_to_beaufort(msec_wind_dict)

Pressure¶

OWM gives barometric pressure in hPa values, in a dict of three pressure items. You can convert these to inHg, which is a common unit of measurement in the United States.

from pyowm.utils import measurables

hpa_pressure_dict = {'press': 1000, 'sea_level': 1000, 'grnd_level': 1000}
inhg_pressure_dict = measurables.metric_pressure_dict_to_inhg(hpa_pressure_dict)

Visibility¶

A typical API response contains a single visibility distance value. This is described as the average visibility in meters. You can convert this value (from meters) using the function provided to either kms or miles.

from pyowm.utils import measurables

visibility = 1000

# the default return value is in kilometers
visibility_kms = measurables.visibility_distance_to(visibility)
visibility_miles = measurables.visibility_distance_to(visibility, 'miles')

`timestamps` module¶

All datetime.datetime objects returned by PyOWM are UTC offset-aware

from pyowm.utils import timestamps

timestamps.now()                                         # Current time in `datetime.datetime` object (default)
timestamps.now('unix')                                   # epoch
timestamps.now('iso')                                    # ISO8601-formatted str (YYYY-MM-DD HH:MM:SS+00:00)

timestamps.tomorrow()                                    # Tomorrow at this time
timestamps.tomorrow(18, 7)                               # Tomorrow at 6:07 PM
timestamps.yesterday(11, 27)                             # Yesterday at 11:27 AM

timestamps.next_three_hours()                            # 3 hours from now
timestamps.last_three_hours(date=timestamps.tomorrow())  # tomorrow but 3 hours before this time

timestamps.next_hour()
timestamps.last_hour(date=timestamps.yesterday())        # yesterday but 1 hour before this time


# And so on with: next_week/last_week/next_month/last_month/next_year/last_year

PyOWM utility functions usage example¶

`config` module¶

`formatting` module¶

`geo` module¶

Common geometry methods¶

`Point` class¶

From City IDs to `Point` objects¶

`MultiPoint` class¶

`Polygon` class¶

`MultiPolygon` class¶

Building geometries¶

`measurables` module¶

Temperature¶

Wind¶

Pressure¶

Visibility¶

`timestamps` module¶

Table of Contents

Related Topics

This Page

PyOWM utility functions usage example¶

config module¶

formatting module¶

geo module¶

Common geometry methods¶

Point class¶

From City IDs to Point objects¶

MultiPoint class¶

Polygon class¶

MultiPolygon class¶

Building geometries¶

measurables module¶

Temperature¶

Wind¶

Pressure¶

Visibility¶

timestamps module¶

`config` module¶

`formatting` module¶

`geo` module¶

`Point` class¶

From City IDs to `Point` objects¶

`MultiPoint` class¶

`Polygon` class¶

`MultiPolygon` class¶

`measurables` module¶

`timestamps` module¶