Async API

Classes for handling OpenWeatherMap API requests asnychronously. These classes are designed to be used with the corresponding OpenWeatherMap API endpoints.

Example

If you want to use the One Call API, you can create an instance of the OneCallAPI class.

class openweatherwrap.asyncapi.AirPollutionAPI(api_key, location, language='en', units='standard')

Bases: OpenWeatherMapAPI

Asynchronous class for handling OpenWeatherMap Air Pollution API requests. This class is designed to be used with the Air Pollution API endpoint.

async get_air_pollution()

Asynchronously fetches air pollution data from the Air Pollution API.

Returns:

An instance of AirPollutionResponse containing the air pollution data.

Return type:

AirPollutionResponse

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

async get_air_pollution_forecast()

Asynchronously fetches air pollution forecast data from the Air Pollution API.

Returns:

An instance of AirPollutionResponse containing the air pollution forecast data.

Return type:

AirPollutionResponse

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

async get_air_pollution_history(start, end)

Asynchronously fetches historical air pollution data from the Air Pollution API.

Parameters:

• start (int) – Start time in UNIX timestamp format.

• end (int) – End time in UNIX timestamp format.

Returns:

An instance of AirPollutionResponse containing the historical air pollution data.

Return type:

AirPollutionResponse

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

class openweatherwrap.asyncapi.CurrentWeatherAPI(api_key, location, language='en', units='standard', mode='json')

Bases: OpenWeatherMapAPI

Asynchronous class for handling OpenWeatherMap Current Weather API requests. This class is designed to be used with the Current Weather API endpoint.

async get_weather()

Asynchronously fetches current weather data from the Current Weather API.

Returns:

An instance of CurrentWeatherResponse containing the current weather data.

Return type:

str | CurrentWeatherResponse

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

class openweatherwrap.asyncapi.FiveDayForecast(api_key, location, count=-1, language='en', units='standard', mode='json')

Bases: OpenWeatherMapAPI

Asynchronous class for handling OpenWeatherMap 5-Day Forecast API requests. This class is designed to be used with the 5-Day Forecast API endpoint.

async get_forecast()

Asynchronously fetches the 5-day weather forecast data from the 5-Day Forecast API.

Returns:

An instance of FiveDayForecastResponse containing the forecast data.

Return type:

FiveDayForecastResponse

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

class openweatherwrap.asyncapi.GeocodingAPI(api_key)

Bases: OpenWeatherMapAPI

Asynchronous class for handling OpenWeatherMap Geocoding API requests. This class is designed to be used with the Geocoding API endpoint.

async get_by_city(city, country, state_code=None, limit=1)

Fetches geocoding data for a city and country.

Parameters:

• city (str) – The name of the city.

• country (str) – The country code (ISO 3166-1 alpha-2).

• state_code (str, optional) – The state code, only for US states.

• limit (int, optional) – Maximum number of results to return. Defaults to 1.

Returns:

An instance of GeocodingResponse containing the geocoding data.

Return type:

GeocodingResponse

async get_by_coordinates(latitude, longitude, limit=1)

Fetches the geocoding data for a set of coordinates from the OpenWeatherMap API and returns the response.

Parameters:

• latitude (float) – Latitude of the location.

• longitude (float) – Longitude of the location.

• limit (int, optional) – Number of results to return (default is 1, maximum is 5).

Returns:

Object containing the geocoding data.

Return type:

GeocodingResponse

Raises:

• ValueError – If limit > 5 or limit < 1.

• ValueError – If latitude is not between -90 and 90, and longitude is not between -180 and 180.

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

async get_by_zip(zip_code, country)

Fetches geocoding data for a zip code and country.

Parameters:

• zip_code (str) – The zip code.

• country (str) – The country code (ISO 3166-1 alpha-2).

Returns:

An instance of GeocodingResponse containing the geocoding data.

Return type:

GeocodingResponse

class openweatherwrap.asyncapi.OneCallAPI(api_key, location, language='en', units='standard')

Bases: OpenWeatherMapAPI

Asynchronous class for handling OpenWeatherMap One Call API requests. This class is designed to be used with the One Call API endpoint.

async get_aggregation(date)

Asynchronously fetches the weather data for a specific date from the one call API and returns the response as a OneCallResponse object`.

Parameters:

date (str) – Date in the ISO 8601 format ‘YYYY-MM-DD’ for which to fetch the weather data.

Returns:

Object containing the weather data for the specified date.

Return type:

OneCallResponse

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

async get_overview()

Asynchronously fetches a brief, human-readable overview of the weather data for the specified location.

Returns:

A brief overview of the weather data.

Return type:

str

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

async get_timed_weather(timestamp)

Asynchronously fetches weather data for a specific timestamp from the One Call API.

Parameters:

timestamp (int) – The Unix timestamp for which to fetch the weather data.

Returns:

An instance of OneCallResponse containing the weather data for the specified timestamp.

Return type:

OneCallResponse

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

• ValueError – If the timestamp is before January 1, 1979.

• ValueError – If the timestamp is not a valid UNIX timestamp.

async get_weather(exclude=[])

Asynchronously fetches weather data from the One Call API.

Parameters:

exclude (list[Literal['current', 'minutely', 'hourly', 'daily', 'alerts']], optional) – List of data types to exclude from the response. Defaults to an empty list, which means no data types are excluded.

Returns:

An instance of OneCallResponse containing the weather data.

Return type:

OneCallResponse

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

class openweatherwrap.asyncapi.WeatherMapsAPI(api_key)

Bases: OpenWeatherMapAPI

Asynchronous class for handling OpenWeatherMap Weather Map API requests. This class is designed to be used with the Weather Map API endpoint.

async download_weathermap(layer, x, y, zoom, filename)

Downloads the weather map image for a specific layer and coordinates to a file.

The pixel coordinate can be calculated using the following formula:

\[pixel\_coordinate = world\_coordinate * 2^{zoom}\]

You can read more here.

Parameters:

• layer (Literal["clouds_new", "precipitation_new", "pressure_new", "wind_new", "temp_new", "snow_new", "rain_new"]) – The layer to fetch.

• x (int) – X coordinate of the tile.

• y (int) – Y coordinate of the tile.

• zoom (int) – Zoom level.

• filename (str) – The name of the file to save the image to.

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

• ValueError – If the layer is not one of the supported layers.

• ValueError – if zoom is not between 0 and 9 (inclusive).

• ValueError – if the x and y coordinates are not valid.

• OSError – If there is an error writing to the file.

Return type:

None

async get_weathermap(layer, x, y, zoom)

Fetches the weather map image for a specific layer and coordinates.

The pixel coordinate can be calculated using the following formula:

\[pixel = world\_coordinate * 2^{zoom}\]

You can read more here.

Parameters:

• layer (Literal["clouds_new", "precipitation_new", "pressure_new", "wind_new", "temp_new", "snow_new", "rain_new"]) – The layer to fetch.

• x (int) – X coordinate of the tile.

• y (int) – Y coordinate of the tile.

• zoom (int) – Zoom level.

Returns:

The weather map image data.

Return type:

bytes

Raises:

• SubscriptionLevelError – If the API key does not have access to the requested data.

• InvalidAPIKeyError – If the API key is invalid.

• NotFoundError – If the location is not found.

• TooManyRequestsError – If the API rate limit is exceeded.

• OpenWeatherMapException – For internal server errors (500, 502, 503, 504).

• ValueError – If the layer is not one of the supported layers.

• ValueError – if zoom is not between 0 and 9 (inclusive).

• ValueError – if the x and y coordinates are not valid.