API

Classes for handling OpenWeatherMap API requests. 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.api.AirPollutionAPI(api_key, location)

Bases: OpenWeatherMapAPI

Wrapper for the Air Pollution API from OpenWeatherMap.

get_air_pollution_forecast()

Fetches the air pollution forecast data from the OpenWeatherMap API and returns the response.

Returns:

Object 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).

get_air_pollution_history(start, end)

Fetches the historical air pollution data from the OpenWeatherMap API for a specific time range and returns the response.

Parameters:

start (int) – Start timestamp (Unix time) for the historical data.
end (int) – End timestamp (Unix time) for the historical data.

Returns:

Object 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).

get_current_air_pollution()

Fetches the current air pollution data from the OpenWeatherMap API and returns the response.

Returns:

Object 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).

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

Bases: OpenWeatherMapAPI

Wrapper for the Current Weather Data API from OpenWeatherMap.

get_weather()

Fetches the current weather data from the OpenWeatherMap API and returns the response.

Returns:

Returns a string if the mode is ‘html’, otherwise returns a CurrentWeatherResponse object.

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.api.FiveDayForecast(api_key, location, count=-1, language='en', units='standard', mode='json')

Bases: OpenWeatherMapAPI

Fetches the 5-day / 3-hour weather forecast from OpenWeatherMap.

get_forecast()

Fetches the 5-day / 3-hour weather forecast from the OpenWeatherMap API and returns the response.

Returns:

Object 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.api.GeocodingAPI(api_key)

Bases: OpenWeatherMapAPI

Wrapper for the Geocoding API from OpenWeatherMap.

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

Fetches the geocoding data for a city and country from the OpenWeatherMap API and returns the response.

State code applies only to the United States and is optional.

Parameters:

city (str) – City name.
country (str) – Country code (ISO 3166-1 alpha-2).
state_code (str, optional) – Optional state code.
limit (int, optional) – Number of results to return. Defaults to 1.

Returns:

Object containing the geocoding data.

Return type:

GeocodingResponse

Raises:

ValueError – If limit > 5 or limit < 1.
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).

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).

get_by_zip(zip_code, country)

Fetches the geocoding data for a zip code and country from the OpenWeatherMap API and returns the response.

Parameters:

zip_code (str) – Zip code.
country (str) – Country code (ISO 3166-1 alpha-2).

Returns:

Object containing the geocoding data.

Return type:

GeocodingResponse

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.api.OneCallAPI(api_key, location, language='en', units='standard')

Bases: OpenWeatherMapAPI

Wrapper for the One Call API from OpenWeatherMap.

get_aggregation(date)

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).

get_overview()

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

Returns:

A string containing 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).

get_timed_weather(timestamp)

Fetches the weather data for a specific timestamp from the one call API and returns the response as a OneCallResponse object`.

Data is available from January 1, 1979 up to 4 days ahead of the current date.

Parameters:

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

Returns:

Object 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.

get_weather(exclude=[])

Fetches the weather data from the one call API and returns the response as a OneCallResponse object`. The response includes all available weather data for the specified location.

Parameters:

exclude (list[Literal['current', 'minutely', 'hourly', 'daily', 'alerts']], optional) – List of data types to exclude from the response. Options are ‘current’, ‘minutely’, ‘hourly’, ‘daily’, ‘alerts’.

Returns:

Object 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.api.OpenWeatherMapAPI(api_key, location, language='en', units='standard')

Bases: object

Base class for OpenWeatherMap API wrappers.

This class does not make any API calls itself, but provides common functionality for all OpenWeatherMap API wrappers.

class openweatherwrap.api.WeatherMapsAPI(api_key)

Bases: OpenWeatherMapAPI

Wrapper for the Weather Map API from OpenWeatherMap.

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

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.