pyowm.weatherapi25 package

Subpackages

Submodules

pyowm.weatherapi25.forecast module

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

classmethod from_dict(the_dict)[source]

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

Parameters

the_dict (dict) – the input dictionary

Returns

a Forecast instance or None if no data is available

Raises

ParseAPIResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the input dictionary embeds an HTTP status error

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

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+00date for datetime.datetime object instance

Returns

an int or a str

Raises

ValueError

to_dict()[source]

Dumps object to a dictionary

Returns

a dict

pyowm.weatherapi25.forecaster module

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

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

Returns

a list of Weather objects

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_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_clear_at(timeobject)[source]

Tells if at the specified time the condition is clear sky. 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_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_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_clear()[source]

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

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_tornado()[source]

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

Returns

boolean

pyowm.weatherapi25.historian module

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

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

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

classmethod from_dict(the_dict)[source]

Parses a Location instance out of a data dictionary. Only certain properties of the data dictionary are used: if these properties are not found or cannot be parsed, an exception is issued.

Parameters

the_dict (dict) – the input dictionary

Returns

a Location instance or None if no data is available

Raises

ParseAPIResponseError if it is impossible to find or parse the data needed to build the result

to_dict()[source]

Dumps object to a dictionary

Returns

a dict

to_geopoint()[source]

Returns the geoJSON compliant representation of this location

Returns

a pyowm.utils.geo.Point instance

pyowm.weatherapi25.observation module

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

classmethod from_dict(the_dict)[source]

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

Parameters

the_dict (dict) – the input dictionary

Returns

an Observation instance or None if no data is available

Raises

ParseAPIResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the input dict embeds an HTTP status error

classmethod from_dict_of_lists(the_dict)[source]

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

Parameters

the_dict (dict) – the input dictionary

Returns

a list of Observation instances or None if no data is available

Raises

ParseAPIResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the OWM API returns an HTTP status error

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+00date for datetime.datetime object instance

Returns

an int or a str

Raises

ValueError when negative values are provided

to_dict()[source]

Dumps object to a dictionary

Returns

a dict

pyowm.weatherapi25.stationhistory module

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

classmethod from_dict(d)[source]

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

Parameters

the_dict (dict) – the input dictionary

Returns

a StationHistory instance or None if no data is available

Raises

ParseAPIResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the input dict embeds an HTTP status error

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+00date for datetime.datetime object instance

Returns

an int or a str

Raises

ValueError

to_dict()[source]

Dumps object to a dictionary

Returns

a dict

pyowm.weatherapi25.weather module

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, utc_offset=None, uvi=None)[source]

Bases: object

A class encapsulating raw weather data. A reference about OWM weather codes and icons can be found at: https://openweathermap.org/weather-conditions

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 (str) – weather-related icon name

  • visibility_distance (float) – visibility distance

  • dewpoint (float) – dewpoint

  • humidex (float) – Canadian humidex

  • heat_index (float) – heat index

  • utc_offset (int or None) – offset with UTC time zone in seconds

  • uvi (int, float or None) – UV index

Returns

a Weather instance

Raises

ValueError when negative values are provided for non-negative quantities

classmethod from_dict(the_dict)[source]

Parses a Weather instance out of a data dictionary. Only certain properties of the data dictionary are used: if these properties are not found or cannot be parsed, an exception is issued.

Parameters

the_dict (dict) – the input dictionary

Returns

a Weather instance or None if no data is available

Raises

ParseAPIResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the input dict embeds an HTTP status error

classmethod from_dict_of_lists(the_dict)[source]

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

Parameters

the_dict (dict) – the input dict

Returns

a list of Weather instances or None if no data is available

Raises

ParseAPIResponseError if it is impossible to find or parse the data needed to build the result, APIResponseError if the input dict an HTTP status error

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 or a datetime.datetime object

Raises

ValueError when negative values are provided

sunrise_time(timeformat='unix')[source]

Returns the GMT time of sunrise. Can be None in case of polar nights.

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

‘None`, an int, a str or a datetime.datetime object

Raises

ValueError

sunset_time(timeformat='unix')[source]

Returns the GMT time of sunset. Can be None in case of polar days.

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

‘None`, an int, a str or a datetime.datetime object

Raises

ValueError

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

to_dict()[source]

Dumps object to a dictionary

Returns

a dict

weather_icon_url(size='')[source]

Returns weather-related icon URL as a string.

Parameters

size (str) – the size of the icon, normal (default, like the old ones), 2x or 4x

Returns

the icon URL.

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), ‘miles_hour, ‘km_hour’, ‘knots’ or ‘beaufort

Returns

a dict containing wind info

pyowm.weatherapi25.weather_manager module

class pyowm.weatherapi25.weather_manager.WeatherManager(API_key, config)[source]

Bases: object

A manager objects that provides a full interface to OWM Weather API.

Parameters
  • API_key (str) – the OWM AirPollution API key

  • config (dict) – the configuration dictionary

Returns

a WeatherManager instance

Raises

AssertionError when no API Key is provided

forecast_at_coords(lat, lon, interval, limit=None)[source]

Queries the OWM Weather API for weather forecast for the specified geographic coordinates with the given time granularity. A Forecaster object is returned, containing a Forecast: this instance encapsulates Weather objects corresponding to the provided granularity.

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

  • interval (str among 3h and ‘daily’) – the granularity of the forecast, among 3h and ‘daily’

  • limit (int or None) – the maximum number of 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 Weather API responses’ data cannot be parsed, APICallException when OWM Weather API can not be reached

forecast_at_id(id, interval, limit=None)[source]

Queries the OWM Weather API for weather forecast for the specified city ID (eg: 5128581) with the given time granularity. A Forecaster object is returned, containing a Forecast: this instance encapsulates Weather objects corresponding to the provided granularity.

Parameters
  • id (int) – the location’s city ID

  • interval (str among 3h and ‘daily’) – the granularity of the forecast, among 3h and ‘daily’

  • limit (int or None) – the maximum number of 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 Weather API responses’ data cannot be parsed, APICallException when OWM Weather API can not be reached

forecast_at_place(name, interval, limit=None)[source]

Queries the OWM Weather API for weather forecast for the specified location (eg: “London,uk”) with the given time granularity. A Forecaster object is returned, containing a Forecast: this instance encapsulates Weather objects corresponding to the provided granularity.

Parameters
  • name (str) – the location’s toponym

  • interval (str among 3h and ‘daily’) – the granularity of the forecast, among 3h and ‘daily’

  • limit (int or None) – the maximum number of 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 Weather API responses’ data cannot be parsed, APICallException when OWM Weather API can not be reached

one_call(lat: Union[int, float], lon: Union[int, float], **kwargs) → pyowm.weatherapi25.one_call.OneCall[source]

Queries the OWM Weather API with one call for current weather information and forecast for the specified geographic coordinates. One Call API provides the following weather data for any geographical coordinate: - Current weather - Hourly forecast for 48 hours - Daily forecast for 7 days

A OneCall object is returned with the current data and the two forecasts.

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 OneCall instance or None if the data is not available for the specified location

Raises

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

one_call_history(lat: Union[int, float], lon: Union[int, float], dt: int = None)[source]

Queries the OWM Weather API with one call for historical weather information for the specified geographic coordinates.

A OneCall object is returned with the current data and the two forecasts.

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

  • dt (int) – timestamp from when the historical data starts. Cannot be less then now - 5 days. Default = None means now - 5 days

Returns

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

Raises

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

station_day_history(station_ID, limit=None)[source]

Queries the OWM Weather 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 Weather API responses’ data cannot be parsed, APICallException when OWM Weather API can not be reached, ValueError if the limit value is negative

station_hour_history(station_ID, limit=None)[source]

Queries the OWM Weather 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 Weather API responses’ data cannot be parsed, APICallException when OWM Weather API can not be reached, ValueError if the limit value is negative

station_tick_history(station_ID, limit=None)[source]

Queries the OWM Weather 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 Weather API responses’ data cannot be parsed, APICallException when OWM Weather API can not be reached, ValueError if the limit value is negative

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

Queries the OWM Weather 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 Weather API responses’ data cannot be parsed, APICallException when OWM Weather 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 Weather 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 Weather API responses’ data cannot be parsed or APICallException when OWM Weather API can not be reached

weather_at_id(id)[source]

Queries the OWM Weather 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 Weather API responses’ data cannot be parsed or APICallException when OWM Weather API can not be reached

weather_at_ids(ids_list)[source]

Queries the OWM Weather 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 Weather API responses’ data cannot be parsed or APICallException when OWM Weather API can not be reached

weather_at_place(name)[source]

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

Parameters

name (str) – the location’s toponym

Returns

an Observation instance or None if no weather data is available

Raises

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

weather_at_places(pattern, searchtype, limit=None)[source]

Queries the OWM Weather 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 Weather API responses’ data cannot be parsed, APICallException when OWM Weather API can not be reached, ValueError when bad value is supplied for the search type or the maximum number of items retrieved

weather_at_places_in_bbox(lon_left, lat_bottom, lon_right, lat_top, zoom=10, cluster=False)[source]

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

Parameters
  • lat_top (int/float) – latitude for top margin of bounding box, must be between -90.0 and 90.0

  • lon_left (int/float) – longitude for left margin of bounding box must be between -180.0 and 180.0

  • lat_bottom (int/float) – latitude for the bottom margin of bounding box, must be between -90.0 and 90.0

  • lon_right (int/float) – longitude for the right margin of bounding box, must be between -180.0 and 180.0

  • zoom (int) – zoom level (defaults to: 10)

  • cluster (bool) – use server clustering of points

Returns

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

Raises

ParseResponseException when OWM Weather API responses’ data cannot be parsed, APICallException when OWM Weather 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 Weather 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 Weather API responses’ data cannot be parsed or APICallException when OWM Weather API can not be reached

pyowm.weatherapi25.weathercoderegistry module

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

classmethod get_instance()[source]

Factory method returning the default weather code registry :return: 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