pyowm.webapi25 package

Submodules

pyowm.webapi25.cityidregistry module

class pyowm.webapi25.cityidregistry.CityIDRegistry(filepath_regex)[source]
MATCHINGS = {'exact': <function <lambda>>, 'like': <function <lambda>>, 'nocase': <function <lambda>>}
id_for(*args, **kwargs)[source]

Returns the long ID corresponding to the first city found that matches the provided city name. The lookup is case insensitive.

Deprecated since version 3.0.0: Use ids_for() instead.

Parameters:city_name (str) – the city name whose ID is looked up
Returns:a long or None if the lookup fails
ids_for(city_name, country=None, matching='nocase')[source]

Returns a list of tuples in the form (long, str, str) corresponding to the int IDs and relative toponyms and 2-chars country of the cities matching the provided city name. The rule for identifying matchings is according to the provided matching parameter value. If country is provided, the search is restricted to the cities of the specified country. :param country: two character str representing the country where to search for the city. Defaults to None, which means: search in all countries. :param matching: str among exact (literal, case-sensitive matching), nocase (literal, case-insensitive matching) and like (matches cities whose name contains as a substring the string fed to the function, no matter the case). Defaults to nocase. :raises ValueError if the value for matching is unknown :return: list of tuples

location_for(*args, **kwargs)[source]

Returns the Location object corresponding to the first city found that matches the provided city name. The lookup is case insensitive.

Parameters:city_name (str) – the city name you want a Location for
Returns:a Location instance or None if the lookup fails

Deprecated since version 3.0.0: Use locations_for() instead.

locations_for(city_name, country=None, matching='nocase')[source]

Returns a list of Location objects corresponding to the int IDs and relative toponyms and 2-chars country of the cities matching the provided city name. The rule for identifying matchings is according to the provided matching parameter value. If country is provided, the search is restricted to the cities of the specified country. :param country: two character str representing the country where to search for the city. Defaults to None, which means: search in all countries. :param matching: str among exact (literal, case-sensitive matching), nocase (literal, case-insensitive matching) and like (matches cities whose name contains as a substring the string fed to the function, no matter the case). Defaults to nocase. :raises ValueError if the value for matching is unknown :return: list of webapi25.location.Location objects

pyowm.webapi25.configuration25 module

pyowm.webapi25.forecast module

Module containing weather forecast classes and data structures.

class pyowm.webapi25.forecast.Forecast(interval, reception_time, location, weathers)[source]

Bases: object

A class encapsulating weather forecast data for a certain location and relative to a specific time interval (forecast for every three hours or for every day)

Parameters:
  • interval (str) – the time granularity of the forecast. May be: ‘3h’ for three hours forecast or ‘daily’ for daily ones
  • reception_time (int) – GMT UNIXtime of the forecast reception from the OWM web API
  • location (Location) – the Location object relative to the forecast
  • weathers (list) – the list of Weather objects composing the forecast
Returns:

a Forecast instance

Raises:

ValueError when negative values are provided

count_weathers()[source]

Tells how many Weather items compose the forecast

Returns:the Weather objects total
get(index)[source]

Lookups up into the Weather items list for the item at the specified index

Parameters:index (int) – the index of the Weather object in the list
Returns:a Weather object
get_interval()[source]

Returns the time granularity of the forecast

Returns:str
get_location()[source]

Returns the Location object relative to the forecast

Returns:a Location object
get_reception_time(timeformat='unix')[source]
Returns the GMT time telling when the forecast was received
from the OWM web API
Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError
get_weathers()[source]

Returns a copy of the Weather objects list composing the forecast

Returns:a list of Weather objects
set_interval(interval)[source]

Sets the time granularity of the forecast

Parameters:interval (str) – the time granularity of the forecast, may be “3h” or “daily”
to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

class pyowm.webapi25.forecast.ForecastIterator(obj)[source]

Bases: object

Iterator over the list of Weather objects encapsulated in a Forecast class instance

Parameters:obj (object) – the iterable object
Returns:a ForecastIterator instance
next()[source]

Compatibility for Python 2.x, delegates to function: __next__() Returns the next Weather item

Returns:the next Weather item

pyowm.webapi25.forecaster module

Module containing weather forecast abstraction classes and data structures.

class pyowm.webapi25.forecaster.Forecaster(forecast)[source]

Bases: object

A class providing convenience methods for manipulating weather forecast data. The class encapsulates a Forecast instance and provides abstractions on the top of it in order to let programmers exploit weather forecast data in a human-friendly fashion.

Parameters:forecast (Forecast) – a Forecast instance
Returns:a Forecaster instance
get_forecast()[source]

Returns the Forecast instance

Returns:the Forecast instance
get_weather_at(timeobject)[source]

Gives the Weather item in the forecast that is closest in time to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:a Weather object
most_cold()[source]

Returns the Weather object in the forecast having the lowest min temperature. The temperature is retrieved using the get_temperature['temp_min'] call; was ‘temp_min’ key missing for every Weather instance in the forecast, None would be returned.

Returns:a Weather object or None if no item in the forecast is eligible
most_hot()[source]

Returns the Weather object in the forecast having the highest max temperature. The temperature is retrieved using the get_temperature['temp_max'] call; was ‘temp_max’ key missing for every Weather instance in the forecast, None would be returned.

Returns:a Weather object or None if no item in the forecast is eligible
most_humid()[source]

Returns the Weather object in the forecast having the highest humidty.

Returns:a Weather object or None if no item in the forecast is eligible
most_rainy()[source]

Returns the Weather object in the forecast having the highest precipitation volume. The rain amount is retrieved via the get_rain['all'] call; was the ‘all’ key missing for every Weather instance in the forecast,``None`` would be returned.

Returns:a Weather object or None if no item in the forecast is eligible
most_snowy()[source]

Returns the Weather object in the forecast having the highest snow volume. The snow amount is retrieved via the get_snow['all'] call; was the ‘all’ key missing for every Weather instance in the forecast, None would be returned.

Returns:a Weather object or None if no item in the forecast is eligible
most_windy()[source]

Returns the Weather object in the forecast having the highest wind speed. The snow amount is retrieved via the get_wind['speed'] call; was the ‘speed’ key missing for every Weather instance in the forecast, None would be returned.

Returns:a Weather object or None if no item in the forecast is eligible
when_clouds()[source]

Returns a sublist of the Weather list in the forecast, containing only items having clouds as weather condition.

Returns:a list of Weather objects
when_ends(timeformat='unix')[source]

Returns the GMT time of the end of the forecast coverage, which is the time of the most recent Weather item in the forecast

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:a long or a str
Raises:ValueError when invalid time format values are provided
when_fog()[source]

Returns a sublist of the Weather list in the forecast, containing only items having fog as weather condition.

Returns:a list of Weather objects
when_hurricane()[source]

Returns a sublist of the Weather list in the forecast, containing only items having hurricane as weather condition.

Returns:a list of Weather objects
when_rain()[source]

Returns a sublist of the Weather list in the forecast, containing only items having rain as weather condition.

Returns:a list of Weather objects
when_snow()[source]

Returns a sublist of the Weather list in the forecast, containing only items having snow as weather condition.

Returns:a list of Weather objects
when_starts(timeformat='unix')[source]

Returns the GMT time of the start of the forecast coverage, which is the time of the most ancient Weather item in the forecast

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:a long or a str
Raises:ValueError when invalid time format values are provided
when_storm()[source]

Returns a sublist of the Weather list in the forecast, containing only items having storm as weather condition.

Returns:a list of Weather objects
when_sun()[source]

Returns a sublist of the Weather list in the forecast, containing only items having sun as weather condition.

Returns:a list of Weather objects
when_tornado()[source]

Returns a sublist of the Weather list in the forecast, containing only items having tornado as weather condition.

Returns:a list of Weather objects
will_be_cloudy_at(timeobject)[source]

Tells if at the specified time the condition is clouds. The check is performed on the Weather item of the forecast which is closest to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:boolean
will_be_foggy_at(timeobject)[source]

Tells if at the specified time the condition is fog. The check is performed on the Weather item of the forecast which is closest to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:boolean
will_be_hurricane_at(timeobject)[source]

Tells if at the specified time the condition is hurricane. The check is performed on the Weather item of the forecast which is closest to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:boolean
will_be_rainy_at(timeobject)[source]

Tells if at the specified time the condition is rain. The check is performed on the Weather item of the forecast which is closest to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:boolean
will_be_snowy_at(timeobject)[source]

Tells if at the specified time the condition is snow. The check is performed on the Weather item of the forecast which is closest to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:boolean
will_be_stormy_at(timeobject)[source]

Tells if at the specified time the condition is storm. The check is performed on the Weather item of the forecast which is closest to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:boolean
will_be_sunny_at(timeobject)[source]

Tells if at the specified time the condition is sun. The check is performed on the Weather item of the forecast which is closest to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:boolean
will_be_tornado_at(timeobject)[source]

Tells if at the specified time the condition is tornado. The check is performed on the Weather item of the forecast which is closest to the time value conveyed by the parameter

Parameters:timeobject (long/int, datetime.datetime or str)) – may be a UNIX time, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:boolean
will_have_clouds()[source]

Tells if into the forecast coverage exist one or more Weather items related to cloud conditions

Returns:boolean
will_have_fog()[source]

Tells if into the forecast coverage exist one or more Weather items related to fog conditions

Returns:boolean
will_have_hurricane()[source]

Tells if into the forecast coverage exist one or more Weather items related to hurricanes

Returns:boolean
will_have_rain()[source]

Tells if into the forecast coverage exist one or more Weather items related to rain conditions

Returns:boolean
will_have_snow()[source]

Tells if into the forecast coverage exist one or more Weather items related to snow conditions

Returns:boolean
will_have_storm()[source]

Tells if into the forecast coverage exist one or more Weather items related to storms

Returns:boolean
will_have_sun()[source]

Tells if into the forecast coverage exist one or more Weather items related to sun conditions

Returns:boolean
will_have_tornado()[source]

Tells if into the forecast coverage exist one or more Weather items related to tornadoes

Returns:boolean

pyowm.webapi25.forecastparser module

Module containing a concrete implementation for JSONParser abstract class, returning Forecast objects

class pyowm.webapi25.forecastparser.ForecastParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building a Forecast instance out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses a Forecast instance out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:a Forecast instance or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the JSON string embeds an HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.historian module

Module containing weather history abstraction classes and data structures.

class pyowm.webapi25.historian.Historian(station_history)[source]

Bases: object

A class providing convenience methods for manipulating meteostation weather history data. The class encapsulates a StationHistory instance and provides abstractions on the top of it in order to let programmers exploit meteostation weather history data in a human-friendly fashion

Parameters:station_history (StationHistory) – a StationHistory instance
Returns:a Historian instance
average_humidity()[source]

Returns the average value in the humidity series

Returns:a float
Raises:ValueError when the measurement series is empty
average_pressure()[source]

Returns the average value in the pressure series

Returns:a float
Raises:ValueError when the measurement series is empty
average_rain()[source]

Returns the average value in the rain series

Returns:a float
Raises:ValueError when the measurement series is empty
average_temperature(unit='kelvin')[source]

Returns the average value in the temperature series

Parameters:unit (str) – the unit of measure for the temperature values. May be among: ‘kelvin‘ (default), ‘celsius‘ or ‘fahrenheit
Returns:a float
Raises:ValueError when invalid values are provided for the unit of measure or the measurement series is empty
get_station_history()[source]

Returns the StationHistory instance

Returns:the StationHistory instance
humidity_series()[source]

Returns the humidity time series relative to the meteostation, in the form of a list of tuples, each one containing the couple timestamp-value

Returns:a list of tuples
max_humidity()[source]

Returns a tuple containing the max value in the humidity series preceeded by its timestamp

Returns:a tuple
Raises:ValueError when the measurement series is empty
max_pressure()[source]

Returns a tuple containing the max value in the pressure series preceeded by its timestamp

Returns:a tuple
Raises:ValueError when the measurement series is empty
max_rain()[source]

Returns a tuple containing the max value in the rain series preceeded by its timestamp

Returns:a tuple
Raises:ValueError when the measurement series is empty
max_temperature(unit='kelvin')[source]

Returns a tuple containing the max value in the temperature series preceeded by its timestamp

Parameters:unit (str) – the unit of measure for the temperature values. May be among: ‘kelvin‘ (default), ‘celsius‘ or ‘fahrenheit
Returns:a tuple
Raises:ValueError when invalid values are provided for the unit of measure or the measurement series is empty
min_humidity()[source]

Returns a tuple containing the min value in the humidity series preceeded by its timestamp

Returns:a tuple
Raises:ValueError when the measurement series is empty
min_pressure()[source]

Returns a tuple containing the min value in the pressure series preceeded by its timestamp

Returns:a tuple
Raises:ValueError when the measurement series is empty
min_rain()[source]

Returns a tuple containing the min value in the rain series preceeded by its timestamp

Returns:a tuple
Raises:ValueError when the measurement series is empty
min_temperature(unit='kelvin')[source]

Returns a tuple containing the min value in the temperature series preceeded by its timestamp

Parameters:unit (str) – the unit of measure for the temperature values. May be among: ‘kelvin‘ (default), ‘celsius‘ or ‘fahrenheit
Returns:a tuple
Raises:ValueError when invalid values are provided for the unit of measure or the measurement series is empty
pressure_series()[source]

Returns the atmospheric pressure time series relative to the meteostation, in the form of a list of tuples, each one containing the couple timestamp-value

Returns:a list of tuples
rain_series()[source]

Returns the precipitation time series relative to the meteostation, in the form of a list of tuples, each one containing the couple timestamp-value

Returns:a list of tuples
temperature_series(unit='kelvin')[source]

Returns the temperature time series relative to the meteostation, in the form of a list of tuples, each one containing the couple timestamp-value

Parameters:unit (str) – the unit of measure for the temperature values. May be among: ‘kelvin‘ (default), ‘celsius‘ or ‘fahrenheit
Returns:a list of tuples
Raises:ValueError when invalid values are provided for the unit of measure
wind_series()[source]

Returns the wind speed time series relative to the meteostation, in the form of a list of tuples, each one containing the couple timestamp-value

Returns:a list of tuples

pyowm.webapi25.location module

Module containing location-related classes and data structures.

class pyowm.webapi25.location.Location(name, lon, lat, ID, country=None)[source]

Bases: object

A class representing a location in the world. A location is defined through a toponym, a couple of geographic coordinates such as longitude and latitude and a numeric identifier assigned by the OWM web API that uniquely spots the location in the world. Optionally, the country specification may be provided.

Further reference about OWM city IDs can be found at: http://bugs.openweathermap.org/projects/api/wiki/Api_2_5_weather#3-By-city-ID

Parameters:
  • name (Unicode) – the location’s toponym
  • lon (int/float) – the location’s longitude, must be between -180.0 and 180.0
  • lat (int/float) – the location’s latitude, must be between -90.0 and 90.0
  • ID (int) – the location’s OWM city ID
  • country (Unicode) – the location’s country (None by default)
Returns:

a Location instance

Raises:

ValueError if lon or lat values are provided out of bounds

get_ID()[source]

Returns the OWM city ID of the location

Returns:the int OWM city ID
get_country()[source]

Returns the country of the location

Returns:the Unicode country
get_lat()[source]

Returns the latitude of the location

Returns:the float latitude
get_lon()[source]

Returns the longitude of the location

Returns:the float longitude
get_name()[source]

Returns the toponym of the location

Returns:the Unicode toponym
to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

pyowm.webapi25.location.location_from_dictionary(d)[source]

Builds a Location object out of a data dictionary. Only certain properties of the dictionary are used: if these properties are not found or cannot be read, an error is issued.

Parameters:d (dict) – a data dictionary
Returns:a Location instance
Raises:KeyError if it is impossible to find or read the data needed to build the instance

pyowm.webapi25.observation module

Weather observation classes and data structures.

class pyowm.webapi25.observation.Observation(reception_time, location, weather)[source]

Bases: object

A class representing the weather which is currently being observed in a certain location in the world. The location is represented by the encapsulated Location object while the observed weather data are held by the encapsulated Weather object.

Parameters:
  • reception_time (int) – GMT UNIXtime telling when the weather obervation has been received from the OWM web API
  • location (Location) – the Location relative to this observation
  • weather (Weather) – the Weather relative to this observation
Returns:

an Observation instance

Raises:

ValueError when negative values are provided as reception time

get_location()[source]

Returns the Location object for this observation

Returns:the Location object
get_reception_time(timeformat='unix')[source]
Returns the GMT time telling when the observation has been received
from the OWM web API
Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError when negative values are provided
get_weather()[source]

Returns the Weather object for this observation

Returns:the Weather object
to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

pyowm.webapi25.observationlistparser module

Module containing a concrete implementation for JSONParser abstract class, returning lists of Observation objects

class pyowm.webapi25.observationlistparser.ObservationListParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building a list of Observation instances out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses a list of Observation instances out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:a list of Observation instances or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the OWM API returns a HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.observationparser module

Module containing a concrete implementation for JSONParser abstract class, returning Observation objects

class pyowm.webapi25.observationparser.ObservationParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building an Observation instance out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses an Observation instance out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:an Observation instance or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the JSON string embeds an HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.owm25 module

Module containing the PyOWM library main entry point

class pyowm.webapi25.owm25.OWM25(parsers, API_key=None, cache=<pyowm.caches.nullcache.NullCache>, language='en', subscription_type='free')[source]

Bases: pyowm.abstractions.owm.OWM

OWM_API_VERSION = '2.5'

OWM subclass providing methods for each OWM web API 2.5 endpoint. The class is instantiated with jsonparser subclasses, each one parsing the response payload of a specific API endpoint

Parameters:
  • parsers (dict) – the dictionary containing jsonparser concrete instances to be used as parsers for OWM web API 2.5 responses
  • API_key (str) – the OWM web API key (defaults to None)
  • cache (an OWMCache concrete instance) – a concrete implementation of class OWMCache serving as the cache provider (defaults to a NullCache instance)
  • language (str) – the language in which you want text results to be returned. It’s a two-characters string, eg: “en”, “ru”, “it”. Defaults to: “en”
  • subscription_type (str) – the type of OWM web API subscription to be wrapped. Can be ‘free’ (free subscription) or ‘pro’ (paid subscription), Defaults to: ‘free’
Returns:

an OWM25 instance

city_id_registry()[source]

Gives the CityIDRegistry singleton instance that can be used to lookup for city IDs.

Returns:a CityIDRegistry instance
coindex_around_coords(lat, lon, start=None, interval=None)[source]

Queries the OWM web API for Carbon Monoxide values sampled in the surroundings of the provided geocoordinates and in the specified time interval. A COIndex object instance is returned, encapsulating a Location object and the list of CO samples If start is not provided, the latest available CO samples are retrieved If start is provided but interval is not, then interval defaults to the maximum extent, which is: year

Parameters:
  • lat (int/float) – the location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – the location’s longitude, must be between -180.0 and 180.0
  • start (int, datetime.datetime or ISO8601-formatted string) – the object conveying the start value of the search time window start (defaults to None). If not provided, the latest available CO samples value are retrieved
  • interval (str among: 'minute', 'hour', 'day', 'month, 'year') – the length of the search time window starting at start (defaults to None). If not provided, ‘year’ is used
Returns:

a COIndex instance or None if data is not available

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError for wrong input values

daily_forecast(name, limit=None)[source]

Queries the OWM web API for daily weather forecast for the specified location (eg: “London,uk”). A Forecaster object is returned, containing a Forecast instance covering a global streak of fourteen days by default: this instance encapsulates Weather objects, with a time interval of one day one from each other

Parameters:
  • name (str or unicode) – the location’s toponym
  • limit (int or None) – the maximum number of daily Weather items to be retrieved (default is None, which stands for any number of items)
Returns:

a Forecaster instance or None if forecast data is not available for the specified location

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError if negative values are supplied for limit

daily_forecast_at_coords(lat, lon, limit=None)[source]

Queries the OWM web API for daily weather forecast for the specified geographic coordinate (eg: latitude: 51.5073509, longitude: -0.1277583). A Forecaster object is returned, containing a Forecast instance covering a global streak of fourteen days by default: this instance encapsulates Weather objects, with a time interval of one day one from each other

Parameters:
  • lat (int/float) – location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – location’s longitude, must be between -180.0 and 180.0
  • limit (int or None) – the maximum number of daily Weather items to be retrieved (default is None, which stands for any number of items)
Returns:

a Forecaster instance or None if forecast data is not available for the specified location

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError if negative values are supplied for limit

daily_forecast_at_id(id, limit=None)[source]

Queries the OWM web API for daily weather forecast for the specified city ID (eg: 5128581). A Forecaster object is returned, containing a Forecast instance covering a global streak of fourteen days by default: this instance encapsulates Weather objects, with a time interval of one day one from each other

Parameters:
  • id (int) – the location’s city ID
  • limit (int or None) – the maximum number of daily Weather items to be retrieved (default is None, which stands for any number of items)
Returns:

a Forecaster instance or None if forecast data is not available for the specified location

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError if negative values are supplied for limit

get_API_key()[source]

Returns the str OWM API key

Returns:a str
get_API_version(*args, **kwargs)[source]

Returns the currently supported OWM web API version

Deprecated since version 3.0.0: Will return a tuple instead of a str

Returns:str
get_language()[source]

Returns the language in which the OWM web API shall return text results

Returns:the language
get_subscription_type()[source]

Returns the OWM API subscription type

Returns:the subscription type
get_version(*args, **kwargs)[source]

Returns the current version of the PyOWM library

Deprecated since version 3.0.0: Will return a tuple instead of a str

Returns:str
is_API_online()[source]

Returns True if the OWM web API is currently online. A short timeout is used to determine API service availability.

Returns:bool
ozone_around_coords(lat, lon, start=None, interval=None)[source]

Queries the OWM web API for Ozone (O3) value in Dobson Units sampled in the surroundings of the provided geocoordinates and in the specified time interval. An Ozone object instance is returned, encapsulating a Location object and the UV intensity value. If start is not provided, the latest available ozone value is retrieved. If start is provided but interval is not, then interval defaults to the maximum extent, which is: year

Parameters:
  • lat (int/float) – the location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – the location’s longitude, must be between -180.0 and 180.0
  • start (int, datetime.datetime or ISO8601-formatted string) – the object conveying the start value of the search time window start (defaults to None). If not provided, the latest available Ozone value is retrieved
  • interval (str among: 'minute', 'hour', 'day', 'month, 'year') – the length of the search time window starting at start (defaults to None). If not provided, ‘year’ is used
Returns:

an Ozone instance or None if data is not available

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError for wrong input values

set_API_key(API_key)[source]

Updates the str OWM API key

Parameters:API_key (str) – the new str API key
set_language(language)[source]

Sets the language in which the OWM web API shall return text results

Parameters:language – the new two-characters language (eg: “ru”)
station_at_coords(lat, lon, limit=None)[source]

Queries the OWM web API for weather stations nearest to the specified geographic coordinates (eg: latitude: 51.5073509, longitude: -0.1277583). A list of Station objects is returned, this instance encapsulates a last reported Weather object.

Parameters:
  • lat (int/float) – location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – location’s longitude, must be between -180.0 and 180.0
  • cnt (int or None) – the maximum number of Station items to be retrieved (default is None, which stands for any number of items)
Returns:

a list of Station objects or None if station data is not available for the specified location

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached

station_day_history(station_ID, limit=None)[source]

Queries the OWM web API for historic weather data measurements for the specified meteostation (eg: 2865), sampled once a day. A Historian object instance is returned, encapsulating a StationHistory objects which contains the measurements. The total number of retrieved data points can be limited using the appropriate parameter

Parameters:
  • station_ID (int) – the numeric ID of the meteostation
  • limit (int or None) – the maximum number of data points the result shall contain (default is None, which stands for any number of data points)
Returns:

a Historian instance or None if data is not available for the specified meteostation

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError if the limit value is negative

station_hour_history(station_ID, limit=None)[source]

Queries the OWM web API for historic weather data measurements for the specified meteostation (eg: 2865), sampled once a hour. A Historian object instance is returned, encapsulating a StationHistory objects which contains the measurements. The total number of retrieved data points can be limited using the appropriate parameter

Parameters:
  • station_ID (int) – the numeric ID of the meteostation
  • limit (int or None) – the maximum number of data points the result shall contain (default is None, which stands for any number of data points)
Returns:

a Historian instance or None if data is not available for the specified meteostation

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError if the limit value is negative

station_tick_history(station_ID, limit=None)[source]

Queries the OWM web API for historic weather data measurements for the specified meteostation (eg: 2865), sampled once a minute (tick). A StationHistory object instance is returned, encapsulating the measurements: the total number of data points can be limited using the appropriate parameter

Parameters:
  • station_ID (int) – the numeric ID of the meteostation
  • limit (int or None) – the maximum number of data points the result shall contain (default is None, which stands for any number of data points)
Returns:

a StationHistory instance or None if data is not available for the specified meteostation

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError if the limit value is negative

three_hours_forecast(name)[source]

Queries the OWM web API for three hours weather forecast for the specified location (eg: “London,uk”). A Forecaster object is returned, containing a Forecast instance covering a global streak of five days: this instance encapsulates Weather objects, with a time interval of three hours one from each other

Parameters:name (str or unicode) – the location’s toponym
Returns:a Forecaster instance or None if forecast data is not available for the specified location
Raises:ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached
three_hours_forecast_at_coords(lat, lon)[source]

Queries the OWM web API for three hours weather forecast for the specified geographic coordinate (eg: latitude: 51.5073509, longitude: -0.1277583). A Forecaster object is returned, containing a Forecast instance covering a global streak of five days: this instance encapsulates Weather objects, with a time interval of three hours one from each other

Parameters:
  • lat (int/float) – location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – location’s longitude, must be between -180.0 and 180.0
Returns:

a Forecaster instance or None if forecast data is not available for the specified location

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached

three_hours_forecast_at_id(id)[source]

Queries the OWM web API for three hours weather forecast for the specified city ID (eg: 5128581). A Forecaster object is returned, containing a Forecast instance covering a global streak of five days: this instance encapsulates Weather objects, with a time interval of three hours one from each other

Parameters:id (int) – the location’s city ID
Returns:a Forecaster instance or None if forecast data is not available for the specified location
Raises:ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached
uvindex_around_coords(lat, lon, start=None, interval=None)[source]

Queries the OWM web API for Ultra Violet value sampled in the surroundings of the provided geocoordinates and in the specified time interval. A UVIndex object instance is returned, encapsulating a Location object and the UV intensity value. If start is not provided, the latest available UVIndex value is retrieved. If start is provided but interval is not, then interval defaults to the maximum extent, which is: year

Parameters:
  • lat (int/float) – the location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – the location’s longitude, must be between -180.0 and 180.0
  • start (int, datetime.datetime or ISO8601-formatted string) – the object conveying the start value of the search time window start (defaults to None). If not provided, the latest available UVIndex value is retrieved
  • interval (str among: 'minute', 'hour', 'day', 'month, 'year') – the length of the search time window starting at start (defaults to None). If not provided, ‘year’ is used
Returns:

a UVIndex instance or None if data is not available

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError for wrong input values

weather_around_coords(lat, lon, limit=None)[source]

Queries the OWM web API for the currently observed weather in all the locations in the proximity of the specified coordinates.

Parameters:
  • lat (int/float) – location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – location’s longitude, must be between -180.0 and 180.0
  • limit – the maximum number of Observation items in the returned list (default is None, which stands for any number of items)
  • limit – int or None
Returns:

a list of Observation objects or None if no weather data is available

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError when coordinates values are out of bounds or negative values are provided for limit

weather_at_coords(lat, lon)[source]

Queries the OWM web API for the currently observed weather at the specified geographic (eg: 51.503614, -0.107331).

Parameters:
  • lat (int/float) – the location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – the location’s longitude, must be between -180.0 and 180.0
Returns:

an Observation instance or None if no weather data is available

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed or APICallException when OWM web API can not be reached

weather_at_id(id)[source]

Queries the OWM web API for the currently observed weather at the specified city ID (eg: 5128581)

Parameters:id (int) – the location’s city ID
Returns:an Observation instance or None if no weather data is available
Raises:ParseResponseException when OWM web API responses’ data cannot be parsed or APICallException when OWM web API can not be reached
weather_at_ids(ids_list)[source]

Queries the OWM web API for the currently observed weathers at the specified city IDs (eg: [5128581,87182])

Parameters:ids_list (list of int) – the list of city IDs
Returns:a list of Observation instances or an empty list if no weather data is available
Raises:ParseResponseException when OWM web API responses’ data cannot be parsed or APICallException when OWM web API can not be reached
weather_at_place(name)[source]

Queries the OWM web API for the currently observed weather at the specified toponym (eg: “London,uk”)

Parameters:name (str or unicode) – the location’s toponym
Returns:an Observation instance or None if no weather data is available
Raises:ParseResponseException when OWM web API responses’ data cannot be parsed or APICallException when OWM web API can not be reached
weather_at_places(pattern, searchtype, limit=None)[source]

Queries the OWM web API for the currently observed weather in all the locations whose name is matching the specified text search parameters. A twofold search can be issued: ‘accurate’ (exact matching) and ‘like’ (matches names that are similar to the supplied pattern).

Parameters:
  • pattern (str) – the string pattern (not a regex) to be searched for the toponym
  • searchtype – the search mode to be used, must be ‘accurate’ for an exact matching or ‘like’ for a likelihood matching
  • limit – the maximum number of Observation items in the returned list (default is None, which stands for any number of items)
  • limit – int or None
Type:

searchtype: str

Returns:

a list of Observation objects or None if no weather data is available

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError when bad value is supplied for the search type or the maximum number of items retrieved

weather_at_station(station_id)[source]

Queries the OWM web API for the weather currently observed by a specific meteostation (eg: 29584)

Parameters:station_id (int) – the meteostation ID
Returns:an Observation instance or None if no weather data is available
Raises:ParseResponseException when OWM web API responses’ data cannot be parsed or APICallException when OWM web API can not be reached
weather_at_stations_in_bbox(lat_top_left, lon_top_left, lat_bottom_right, lon_bottom_right, cluster=False, limit=None)[source]

Queries the OWM web API for the weather currently observed by meteostations inside the bounding box of latitude/longitude coords.

Parameters:
  • lat_top_left (int/float) – latitude for top-left of bounding box, must be between -90.0 and 90.0
  • lon_top_left (int/float) – longitude for top-left of bounding box must be between -180.0 and 180.0
  • lat_bottom_right (int/float) – latitude for bottom-right of bounding box, must be between -90.0 and 90.0
  • lon_bottom_right (int/float) – longitude for bottom-right of bounding box, must be between -180.0 and 180.0
  • cluster (bool) – use server clustering of points
  • limit – the maximum number of Observation items in the returned list (default is None, which stands for any number of items)
  • limit – int or None
Returns:

a list of Observation objects or None if no weather data is available

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError when coordinates values are out of bounds or negative values are provided for limit

weather_at_zip_code(zipcode, country)[source]

Queries the OWM web API for the currently observed weather at the specified zip code and country code (eg: 2037, au).

Parameters:
  • zip (string) – the location’s zip or postcode
  • country (string) – the location’s country code
Returns:

an Observation instance or None if no weather data is available

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed or APICallException when OWM web API can not be reached

weather_history_at_coords(lat, lon, start=None, end=None)[source]

Queries the OWM web API for weather history for the specified at the specified geographic (eg: 51.503614, -0.107331). A list of Weather objects is returned. It is possible to query for weather history in a closed time period, whose boundaries can be passed as optional parameters.

Parameters:
  • lat (int/float) – the location’s latitude, must be between -90.0 and 90.0
  • lon (int/float) – the location’s longitude, must be between -180.0 and 180.0
  • start (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value for the start query boundary (defaults to None)
  • end (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value for the end query boundary (defaults to None)
Returns:

a list of Weather instances or None if history data is not available for the specified location

weather_history_at_id(id, start=None, end=None)[source]

Queries the OWM web API for weather history for the specified city ID. A list of Weather objects is returned. It is possible to query for weather history in a closed time period, whose boundaries can be passed as optional parameters.

Parameters:
  • id (int) – the city ID
  • start (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value for the start query boundary (defaults to None)
  • end (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value for the end query boundary (defaults to None)
Returns:

a list of Weather instances or None if history data is not available for the specified location

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError if the time boundaries are not in the correct chronological order, if one of the time boundaries is not None and the other is or if one or both of the time boundaries are after the current time

weather_history_at_place(name, start=None, end=None)[source]

Queries the OWM web API for weather history for the specified location (eg: “London,uk”). A list of Weather objects is returned. It is possible to query for weather history in a closed time period, whose boundaries can be passed as optional parameters.

Parameters:
  • name (str or unicode) – the location’s toponym
  • start (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value for the start query boundary (defaults to None)
  • end (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value for the end query boundary (defaults to None)
Returns:

a list of Weather instances or None if history data is not available for the specified location

Raises:

ParseResponseException when OWM web API responses’ data cannot be parsed, APICallException when OWM web API can not be reached, ValueError if the time boundaries are not in the correct chronological order, if one of the time boundaries is not None and the other is or if one or both of the time boundaries are after the current time

pyowm.webapi25.station module

Module containing classes and data structures related to meteostation data

class pyowm.webapi25.station.Station(name, station_ID, station_type, status, lat, lon, distance=None, last_weather=None)[source]

Bases: object

A class representing meteostations which are reporting current weather conditions from geographical coordinates.

Parameters:
  • name (string) – meteostation name
  • station_ID (int) – OWM station ID
  • station_type (int) – meteostation type
  • status (int) – station status
  • lat (float) – latitude for station
  • lon (float) – longitude for station
  • distance (float) – distance of station from lat/lon of search criteria
  • last_weather (Weather instance) – last reported weather conditions from station
Returns:

a Station instance

Raises:

ValueError if lon or lat values are provided out of bounds or last_weather is not an instance of Weather or None

get_distance()[source]

Returns the distance of the station from the geo coordinates used in search

Returns:the float distance from geo coordinates
get_last_weather()[source]

Returns the last reported weather conditions reported by the station.

Returns:the last Weather instance reported by station
get_lat()[source]

Returns the latitude of the location

Returns:the float latitude
get_lon()[source]

Returns the longitude of the location

Returns:the float longitude
get_name()[source]

Returns the name of the station

Returns:the Unicode station name
get_station_ID()[source]

Returns the OWM station ID

Returns:the int OWM station ID
get_station_type()[source]

Returns the OWM station type

Returns:the int OWM station type
get_status()[source]

Returns the OWM station status

Returns:the int OWM station status
to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

pyowm.webapi25.stationhistory module

Module containing classes and datastructures related to meteostation history data

class pyowm.webapi25.stationhistory.StationHistory(station_ID, interval, reception_time, measurements)[source]

Bases: object

A class representing historic weather measurements collected by a meteostation. Three types of historic meteostation data can be obtained by the OWM web API: ticks (one data chunk per minute) data, hourly and daily data.

Parameters:
  • station_ID (int) – the numeric ID of the meteostation
  • interval (str) – the time granularity of the meteostation data history
  • reception_time (int) – GMT UNIXtime of the data reception from the OWM web API
  • measurements (dict) – a dictionary containing raw weather measurements
Returns:

a StationHistory instance

Raises:

ValueError when the supplied value for reception time is negative

get_interval()[source]

Returns the interval of the meteostation history data

Returns:the int interval
get_measurements()[source]

Returns the measurements of the meteostation as a dict. The dictionary keys are UNIX timestamps and for each one the value is a dict containing the keys ‘temperature’,’humidity’,’pressure’,’rain’,’wind’ along with their corresponding numeric values. Eg: {1362933983: { "temperature": 266.25, "humidity": 27.3, "pressure": 1010.02, "rain": None, "wind": 4.7}, ... }

Returns:the dict containing the meteostation’s measurements
get_reception_time(timeformat='unix')[source]
Returns the GMT time telling when the meteostation history data was
received from the OWM web API
Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError
get_station_ID()[source]

Returns the ID of the meteostation

Returns:the int station ID
set_interval(interval)[source]

Sets the interval of the meteostation history data

Parameters:interval (string) – the time granularity of the meteostation history data, may be among “tick”,”hour” and “day”
set_station_ID(station_ID)[source]

Sets the numeric ID of the meteostation

Parameters:station_ID (int) – the numeric ID of the meteostation
to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

pyowm.webapi25.stationhistoryparser module

Module containing a concrete implementation for JSONParser abstract class, returning a StationHistory instance

class pyowm.webapi25.stationhistoryparser.StationHistoryParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building a StationHistory instance out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses a StationHistory instance out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:a StationHistory instance or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the JSON string embeds an HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.stationlistparser module

Module containing a concrete implementation for JSONParser abstract class, returning a list of Station instances

class pyowm.webapi25.stationlistparser.StationListParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building a list of Station instances out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses a list of Station instances out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:a list of Station instances or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the OWM API returns a HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.stationparser module

Module containing a concrete implementation for JSONParser abstract class, returning a Station instance

class pyowm.webapi25.stationparser.StationParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building a Station instance out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses a Station instance out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:a Station instance or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the JSON string embeds an HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.weather module

Module containing weather data classes and data structures.

class pyowm.webapi25.weather.Weather(reference_time, sunset_time, sunrise_time, clouds, rain, snow, wind, humidity, pressure, temperature, status, detailed_status, weather_code, weather_icon_name, visibility_distance, dewpoint, humidex, heat_index)[source]

Bases: object

A class encapsulating raw weather data. A reference about OWM weather codes and icons can be found at: http://bugs.openweathermap.org/projects/api/wiki/Weather_Condition_Codes

Parameters:
  • reference_time (int) – GMT UNIX time of weather measurement
  • sunset_time (int or None) – GMT UNIX time of sunset or None on polar days
  • sunrise_time (int or None) – GMT UNIX time of sunrise or None on polar nights
  • clouds (int) – cloud coverage percentage
  • rain (dict) – precipitation info
  • snow (dict) – snow info
  • wind (dict) – wind info
  • humidity (int) – atmospheric humidity percentage
  • pressure (dict) – atmospheric pressure info
  • temperature (dict) – temperature info
  • status (Unicode) – short weather status
  • detailed_status (Unicode) – detailed weather status
  • weather_code (int) – OWM weather condition code
  • weather_icon_name (Unicode) – weather-related icon name
  • visibility_distance (float) – visibility distance
  • dewpoint (float) – dewpoint
  • humidex (float) – Canadian humidex
  • heat_index (float) – heat index
Returns:

a Weather instance

Raises:

ValueError when negative values are provided

get_clouds()[source]

Returns the cloud coverage percentage as an int

Returns:the cloud coverage percentage
get_detailed_status()[source]

Returns the detailed weather status as a Unicode string

Returns:the detailed weather status
get_dewpoint()[source]

Returns the dew point as a float

Returns:the dew point
get_heat_index()[source]

Returns the heat index as a float

Returns:the heat index
get_humidex()[source]

Returns the Canadian humidex as a float

Returns:the Canadian humidex
get_humidity()[source]

Returns the atmospheric humidity as an int

Returns:the humidity
get_pressure()[source]

Returns a dict containing atmospheric pressure info

Returns:a dict containing pressure info
get_rain()[source]

Returns a dict containing precipitation info

Returns:a dict containing rain info
get_reference_time(timeformat='unix')[source]

Returns the GMT time telling when the weather was measured

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError when negative values are provided
get_snow()[source]

Returns a dict containing snow info

Returns:a dict containing snow info
get_status()[source]

Returns the short weather status as a Unicode string

Returns:the short weather status
get_sunrise_time(timeformat='unix')[source]

Returns the GMT time of sunrise

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time or ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:an int or a str or None
Raises:ValueError
get_sunset_time(timeformat='unix')[source]

Returns the GMT time of sunset

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time or ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00
Returns:an int or a str or None
Raises:ValueError
get_temperature(unit='kelvin')[source]

Returns a dict with temperature info

Parameters:unit (str) – the unit of measure for the temperature values. May be: ‘kelvin‘ (default), ‘celsius‘ or ‘fahrenheit
Returns:a dict containing temperature values.
Raises:ValueError when unknown temperature units are provided
get_visibility_distance()[source]

Returns the visibility distance as a float

Returns:the visibility distance
get_weather_code()[source]

Returns the OWM weather condition code as an int

Returns:the OWM weather condition code
get_weather_icon_name()[source]

Returns weather-related icon name as a Unicode string.

Returns:the icon name.
get_wind()[source]

Returns a dict containing wind info

Returns:a dict containing wind info
to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

pyowm.webapi25.weather.weather_from_dictionary(d)[source]

Builds a Weather object out of a data dictionary. Only certain properties of the dictionary are used: if these properties are not found or cannot be read, an error is issued.

Parameters:d (dict) – a data dictionary
Returns:a Weather instance
Raises:KeyError if it is impossible to find or read the data needed to build the instance

pyowm.webapi25.weathercoderegistry module

Module containing weather code lookup and resolution classes

class pyowm.webapi25.weathercoderegistry.WeatherCodeRegistry(code_ranges_dict)[source]

Bases: object

A registry class for looking up weather statuses from weather codes.

Parameters:code_ranges_dict (dict) – a dict containing the mapping between weather statuses (eg: “sun”,”clouds”,etc) and weather code ranges
Returns:a WeatherCodeRegistry instance
status_for(code)[source]

Returns the weather status related to the specified weather status code, if any is stored, None otherwise.

Parameters:code (int) – the weather status code whose status is to be looked up
Returns:the weather status str or None if the code is not mapped

pyowm.webapi25.weatherhistoryparser module

Module containing a concrete implementation for JSONParser abstract class, returning a list of Weather objects

class pyowm.webapi25.weatherhistoryparser.WeatherHistoryParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building a list of Weather instances out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses a list of Weather instances out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:a list of Weather instances or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the JSON string embeds an HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.weatherutils module

Module containing search and filter utilities for Weather objects lists management

pyowm.webapi25.weatherutils.any_status_is(weather_list, status, weather_code_registry)[source]

Checks if the weather status code of any of the Weather objects in the provided list corresponds to the detailed status indicated. The lookup is performed against the provided WeatherCodeRegistry object.

Parameters:
  • weathers (list) – a list of Weather objects
  • status (str) – a string indicating a detailed weather status
  • weather_code_registry (WeatherCodeRegistry) – a WeatherCodeRegistry object
Returns:

True if the check is positive, False otherwise

pyowm.webapi25.weatherutils.filter_by_status(weather_list, status, weather_code_registry)[source]

Filters out from the provided list of Weather objects a sublist of items having a status corresponding to the provided one. The lookup is performed against the provided WeatherCodeRegistry object.

Parameters:
  • weathers (list) – a list of Weather objects
  • status (str) – a string indicating a detailed weather status
  • weather_code_registry (WeatherCodeRegistry) – a WeatherCodeRegistry object
Returns:

True if the check is positive, False otherwise

pyowm.webapi25.weatherutils.find_closest_weather(weathers_list, unixtime)[source]

Extracts from the provided list of Weather objects the item which is closest in time to the provided UNIXtime.

Parameters:
  • weathers_list (list) – a list of Weather objects
  • unixtime (int) – a UNIX time
Returns:

the Weather object which is closest in time or None if the list is empty

pyowm.webapi25.weatherutils.is_in_coverage(unixtime, weathers_list)[source]

Checks if the supplied UNIX time is contained into the time range (coverage) defined by the most ancient and most recent Weather objects in the supplied list

Parameters:
  • unixtime (int) – the UNIX time to be searched in the time range
  • weathers_list (list) – the list of Weather objects to be scanned for global time coverage
Returns:

True if the UNIX time is contained into the time range, False otherwise

pyowm.webapi25.weatherutils.status_is(weather, status, weather_code_registry)[source]

Checks if the weather status code of a Weather object corresponds to the detailed status indicated. The lookup is performed against the provided WeatherCodeRegistry object.

Parameters:
  • weather (Weather) – the Weather object whose status code is to be checked
  • status (str) – a string indicating a detailed weather status
  • weather_code_registry (WeatherCodeRegistry) – a WeatherCodeRegistry object
Returns:

True if the check is positive, False otherwise

pyowm.webapi25.uvindex module

class pyowm.webapi25.uvindex.UVIndex(reference_time, location, interval, value, reception_time)[source]

Bases: object

A class representing the UltraViolet Index observed in a certain location in the world. The location is represented by the encapsulated Location object.

Parameters:
  • reference_time (int) – GMT UNIXtime telling when the UV data have been measured
  • location (Location) – the Location relative to this UV observation
  • value (float) – the observed UV intensity value
  • interval (str) – the time granularity of the UV observation
  • reception_time (int) – GMT UNIXtime telling when the observation has been received from the OWM web API
Returns:

an UVIndex instance

Raises:

ValueError when negative values are provided as reception time or UV intensity value

get_exposure_risk()[source]

Returns a string stating the risk of harm from unprotected sun exposure for the average adult on this UV observation :return: str

get_interval()[source]

Returns the time granularity interval for this UV observation

Returns:str
get_location()[source]

Returns the Location object for this UV observation

Returns:the Location object
get_reception_time(timeformat='unix')[source]

Returns the GMT time telling when the UV has been received from the API

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError when negative values are provided
get_reference_time(timeformat='unix')[source]
Returns the GMT time telling when the UV has been observed
from the OWM web API
Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError when negative values are provided
get_value()[source]

Returns the UV intensity for this observation

Returns:float
is_forecast()[source]

Tells if the current UV observation refers to the future with respect to the current date :return: bool

to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

pyowm.webapi25.uvindex.uv_intensity_to_exposure_risk(uv_intensity)[source]

pyowm.webapi25.uvindexparser module

Module containing a concrete implementation for JSONParser abstract class, returning UVIndex objects

class pyowm.webapi25.uvindexparser.UVIndexParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building an UVIndex instance out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses an UVIndex instance out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:an UVIndex instance or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the JSON string embeds an HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.coindex module

Carbon Monoxide classes and data structures.

class pyowm.webapi25.coindex.COIndex(reference_time, location, interval, co_samples, reception_time)[source]

Bases: object

A class representing the Carbon monOxide Index observed in a certain location in the world. The index is made up of several measurements, each one at a different atmospheric pressure. The location is represented by the encapsulated Location object.

Parameters:
  • reference_time (int) – GMT UNIXtime telling when the CO data has been measured
  • location (Location) – the Location relative to this CO observation
  • interval (str) – the time granularity of the CO observation
  • co_samples (list of dicts) – the CO samples
  • reception_time (int) – GMT UNIXtime telling when the CO observation has been received from the OWM web API
Returns:

an COIndex instance

Raises:

ValueError when negative values are provided as reception time, CO samples are not provided in a list

get_co_sample_with_highest_vmr()[source]

Returns the CO sample with the highest Volume Mixing Ratio value :return: dict

get_co_sample_with_lowest_vmr()[source]

Returns the CO sample with the lowest Volume Mixing Ratio value :return: dict

get_co_samples()[source]

Returns the CO samples for this index

Returns:list of dicts
get_interval()[source]

Returns the time granularity interval for this CO index measurement

Returns:str
get_location()[source]

Returns the Location object for this CO index measurement

Returns:the Location object
get_reception_time(timeformat='unix')[source]

Returns the GMT time telling when the CO observation has been received from the OWM web API

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError when negative values are provided
get_reference_time(timeformat='unix')[source]

Returns the GMT time telling when the CO samples have been measured

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError when negative values are provided
is_forecast()[source]

Tells if the current CO observation refers to the future with respect to the current date :return: bool

to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

pyowm.webapi25.coindexparser module

class pyowm.webapi25.coindexparser.COIndexParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building an COIndex instance out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses an COIndex instance out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:an COIndex instance or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the JSON string embeds an HTTP status error (this is an OWM web API 2.5 bug)

pyowm.webapi25.ozone module

class pyowm.webapi25.ozone.Ozone(reference_time, location, interval, du_value, reception_time)[source]

Bases: object

A class representing the Ozone (O3) data observed in a certain location in the world. The location is represented by the encapsulated Location object.

Parameters:
  • reference_time (int) – GMT UNIXtime telling when the O3 data have been measured
  • location (Location) – the Location relative to this O3 observation
  • du_value (float) – the observed O3 Dobson Units value (reference: http://www.theozonehole.com/dobsonunit.htm)
  • interval (str) – the time granularity of the O3 observation
  • reception_time (int) – GMT UNIXtime telling when the observation has been received from the OWM web API
Returns:

an Ozone instance

Raises:

ValueError when negative values are provided as reception time or du_value

get_du_value()[source]

Returns the O3 Dobson Unit of this observation

Returns:float
get_interval()[source]

Returns the time granularity interval for this O3 observation

Returns:str
get_location()[source]

Returns the Location object for this O3 observation

Returns:the Location object
get_reception_time(timeformat='unix')[source]

Returns the GMT time telling when the O3 observation has been received from the OWM web API

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError when negative values are provided
get_reference_time(timeformat='unix')[source]

Returns the GMT time telling when the O3 data have been measured

Parameters:timeformat (str) – the format for the time value. May be: ‘unix‘ (default) for UNIX time ‘iso‘ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00date for datetime.datetime object instance
Returns:an int or a str
Raises:ValueError when negative values are provided
is_forecast()[source]

Tells if the current O3 observation refers to the future with respect to the current date :return: bool

to_JSON()[source]

Dumps object fields into a JSON formatted string

Returns:the JSON string
to_XML(xml_declaration=True, xmlns=True)[source]

Dumps object fields to an XML-formatted string. The ‘xml_declaration’ switch enables printing of a leading standard XML line containing XML version and encoding. The ‘xmlns’ switch enables printing of qualified XMLNS prefixes.

Parameters:
  • XML_declaration (bool) – if True (default) prints a leading XML declaration line
  • xmlns (bool) – if True (default) prints full XMLNS prefixes
Returns:

an XML-formatted string

pyowm.webapi25.ozone_parser module

Module containing a concrete implementation for JSONParser abstract class, returning UVIndex objects

class pyowm.webapi25.ozone_parser.OzoneParser[source]

Bases: pyowm.abstractions.jsonparser.JSONParser

Concrete JSONParser implementation building an Ozone instance out of raw JSON data coming from OWM web API responses.

parse_JSON(JSON_string)[source]

Parses an Ozone instance out of raw JSON data. Only certain properties of the data are used: if these properties are not found or cannot be parsed, an error is issued.

Parameters:JSON_string (str) – a raw JSON string
Returns:an Ozone instance or None if no data is available
Raises:ParseResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the JSON string embeds an HTTP status error (this is an OWM web API 2.5 bug)

Module contents