pyowm.weatherapi25 package

Submodules

pyowm.weatherapi25.cityidregistry module

pyowm.weatherapi25.configuration25 module

pyowm.weatherapi25.forecast module

Module containing weather forecast classes and data structures.

class pyowm.weatherapi25.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
actualize()[source]

Removes from this forecast all the Weather objects having a reference timestamp in the past with respect to the current timestamp

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 Weather 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+00 ‘date 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.weatherapi25.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.weatherapi25.forecaster module

pyowm.weatherapi25.historian module

Module containing weather history abstraction classes and data structures.

class pyowm.weatherapi25.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.weatherapi25.location module

pyowm.weatherapi25.observation module

Weather observation classes and data structures.

class pyowm.weatherapi25.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 Weather 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 Weather 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+00 ‘date 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.weatherapi25.owm25 module

pyowm.weatherapi25.station module

Module containing classes and data structures related to meteostation data

class pyowm.weatherapi25.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.weatherapi25.stationhistory module

Module containing classes and datastructures related to meteostation history data

class pyowm.weatherapi25.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 Weather 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 Weather 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+00 ‘date 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.weatherapi25.weather module

Module containing weather data classes and data structures.

class pyowm.weatherapi25.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+00 ‘date 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_weather_icon_url()[source]

Returns weather-related icon URL as a Unicode string.

Returns:the icon URL.
get_wind(unit='meters_sec')[source]

Returns a dict containing wind info

Parameters:unit (str) – the unit of measure for the wind values. May be: ‘meters_sec’ (default) or ‘miles_hour’
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.weatherapi25.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.weatherapi25.weathercoderegistry module

Module containing weather code lookup and resolution classes

class pyowm.weatherapi25.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

Module contents