pyowm.airpollutionapi30 package

Subpackages

Submodules

pyowm.airpollutionapi30.airpollution_client module

class pyowm.airpollutionapi30.airpollution_client.AirPollutionHttpClient(API_key, httpclient)[source]

Bases: object

A class representing the OWM Air Pollution web API, which is a subset of the overall OWM API.

Parameters:

  • API_key (Unicode) – a Unicode object representing the OWM Air Pollution web API key

  • httpclient (an httpclient.HttpClient instance) – an httpclient.HttpClient instance that will be used to send requests to the OWM Air Pollution web API.

get_air_pollution(params_dict)[source]

Invokes the new AirPollution API endpoint

Parameters:

params_dict – dict of parameters

Returns:

a string containing raw JSON data

Raises:

ValueError, APIRequestError

get_coi(params_dict)[source]

Invokes the CO Index endpoint

Parameters:

params_dict – dict of parameters

Returns:

a string containing raw JSON data

Raises:

ValueError, APIRequestError

get_forecast_air_pollution(params_dict)[source]

Invokes the new AirPollution API forecast endpoint

Parameters:

params_dict – dict of parameters

Returns:

a string containing raw JSON data

Raises:

ValueError, APIRequestError

get_historical_air_pollution(params_dict)[source]

Invokes the new AirPollution API history endpoint

Parameters:

params_dict – dict of parameters

Returns:

a string containing raw JSON data

Raises:

ValueError, APIRequestError

get_no2(params_dict)[source]

Invokes the NO2 Index endpoint

Parameters:

params_dict – dict of parameters

Returns:

a string containing raw JSON data

Raises:

ValueError, APIRequestError

get_o3(params_dict)[source]

Invokes the O3 Index endpoint

Parameters:

params_dict – dict of parameters

Returns:

a string containing raw JSON data

Raises:

ValueError, APIRequestError

get_so2(params_dict)[source]

Invokes the SO2 Index endpoint

Parameters:

params_dict – dict of parameters

Returns:

a string containing raw JSON data

Raises:

ValueError, APIRequestError

pyowm.airpollutionapi30.airpollution_manager module

class pyowm.airpollutionapi30.airpollution_manager.AirPollutionManager(API_key, config)[source]

Bases: object

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

Parameters:

  • API_key (str) – the OWM AirPollution API key

  • config (dict) – the configuration dictionary

Returns:

an AirPollutionManager instance

Raises:

AssertionError when no API Key is provided

air_quality_at_coords(lat, lon)[source]

Queries the OWM AirPollution API for available air quality indicators around the specified coordinates.

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:

a AirStatus instance or None if data is not available

Raises:

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

air_quality_forecast_at_coords(lat, lon)[source]

Queries the OWM AirPollution API for available forecasted air quality indicators around the specified coordinates.

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:

a list of AirStatus instances or an empty list if data is not available

Raises:

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

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

Queries the OWM AirPollution API for available forecasted air quality indicators around the specified coordinates.

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

  • end (int, datetime.datetime or ISO8601-formatted string) – the object conveying the end value of the search time window. Values in the future will be clipped to the current timestamp. Defaults to the current UNIX timestamp.

Returns:

a list of AirStatus instances or an empty list if data is not available

Raises:

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

airpollution_api_version()[source]
coindex_around_coords(lat, lon, start=None, interval=None)[source]

Queries the OWM AirPollution 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 AirPollution API responses’ data cannot be parsed, APICallException when OWM AirPollution API can not be reached, ValueError for wrong input values

no2index_around_coords(lat, lon, start=None, interval=None)[source]

Queries the OWM AirPollution API for Nitrogen Dioxide values sampled in the surroundings of the provided geocoordinates and in the specified time interval. A NO2Index object instance is returned, encapsulating a Location object and the list of NO2 samples If start is not provided, the latest available NO2 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 NO2 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 NO2Index instance or None if data is not available

Raises:

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

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

Queries the OWM AirPollution 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 AirPollution API responses’ data cannot be parsed, APICallException when OWM AirPollution API can not be reached, ValueError for wrong input values

so2index_around_coords(lat, lon, start=None, interval=None)[source]

Queries the OWM AirPollution API for Sulphur Dioxide values sampled in the surroundings of the provided geocoordinates and in the specified time interval. A SO2Index object instance is returned, encapsulating a Location object and the list of SO2 samples If start is not provided, the latest available SO2 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 SO2 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 SO2Index instance or None if data is not available

Raises:

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

pyowm.airpollutionapi30.coindex module

class pyowm.airpollutionapi30.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 Weather API

Returns:

an COIndex instance

Raises:

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

classmethod from_dict(the_dict)[source]

Parses a COIndex 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 COIndex 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

is_forecast()[source]

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

reception_time(timeformat='unix')[source]

Returns the GMT time telling when the CO 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:00 ‘date for datetime.datetime object instance

Returns:

an int or a str

Raises:

ValueError when negative values are provided

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

Returns:

an int or a str

Raises:

ValueError when negative values are provided

sample_with_highest_vmr()[source]

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

sample_with_lowest_vmr()[source]

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

to_dict()[source]

Dumps object to a dictionary

Returns:

a dict

pyowm.airpollutionapi30.ozone module

class pyowm.airpollutionapi30.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 Weather API

Returns:

an Ozone instance

Raises:

ValueError when negative values are provided as reception time or du_value

classmethod from_dict(the_dict)[source]

Parses an Ozone 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 Ozone 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

is_forecast()[source]

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

reception_time(timeformat='unix')[source]

Returns the GMT time telling when the O3 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:00 ‘date for datetime.datetime object instance

Returns:

an int or a str

Raises:

ValueError when negative values are provided

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+00:00 ‘date 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.airpollutionapi30.no2index module

class pyowm.airpollutionapi30.no2index.NO2Index(reference_time, location, interval, no2_samples, reception_time)[source]

Bases: object

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

Parameters:

  • reference_time (int) – GMT UNIXtime telling when the NO2 data has been measured

  • location (Location) – the Location relative to this NO2 observation

  • interval (str) – the time granularity of the NO2 observation

  • no2_samples (list of dicts) – the NO2 samples

  • reception_time (int) – GMT UNIXtime telling when the NO2 observation has been received from the OWM Weather API

Returns:

a NO2Index instance

Raises:

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

classmethod from_dict(the_dict)[source]

Parses an NO2Index 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 NO2Index 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

get_sample_by_label(label)[source]

Returns the NO2 sample having the specified label or None if none is found

Parameters:

label – the label for the seeked NO2 sample

Returns:

dict or None

is_forecast()[source]

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

reception_time(timeformat='unix')[source]

Returns the GMT time telling when the NO2 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:00 ‘date for datetime.datetime object instance

Returns:

an int or a str

Raises:

ValueError when negative values are provided

reference_time(timeformat='unix')[source]

Returns the GMT time telling when the NO2 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+00:00 ‘date 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.airpollutionapi30.so2index module

class pyowm.airpollutionapi30.so2index.SO2Index(reference_time, location, interval, so2_samples, reception_time)[source]

Bases: object

A class representing the Sulphur Dioxide 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 SO2 data has been measured

  • location (Location) – the Location relative to this SO2 observation

  • interval (str) – the time granularity of the SO2 observation

  • so2_samples (list of dicts) – the SO2 samples

  • reception_time (int) – GMT UNIXtime telling when the SO2 observation has been received from the OWM Weather API

Returns:

an SOIndex instance

Raises:

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

classmethod from_dict(the_dict)[source]

Parses a SO2Index 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 SO2Index 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

is_forecast()[source]

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

reception_time(timeformat='unix')[source]

Returns the GMT time telling when the SO2 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:00 ‘date for datetime.datetime object instance

Returns:

an int or a str

Raises:

ValueError when negative values are provided

reference_time(timeformat='unix')[source]

Returns the GMT time telling when the SO2 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+00:00 ‘date 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

Module contents