SDK for accessing to OpenWeatherAPI and retrieving information about current weather conditions in a specified city. The SDK can operate in two modes: on-demand and polling. In on-demand mode (the default mode), API requests are made on user demand, while in the polling mode, there is regular polling of the API for weather updates in the saved (previously requested) cities.
Available requests (for versions from 1.0.0)
Weather request (for versions up to 1.0.0)
pip install msklv-openweather-sdk
To work with the SDK, you need to obtain an access token for OpenWeatherAPI. More information can be found on FAQ page ("Get started" section -> "How to get an API key").
The only required argument is the access token.
By default, the SDK operates in on-demand mode, returns information in English, uses the metric system of measurements, has a cache size of 10 locations, and the information remains valid for 10 minutes. You can modify this mode by passing additional arguments during client initialization.
Additionally, if you need to modify the behavior of the SDK, you can pass additional arguments.
mode
- determines the operating mode of the SDK. In on-demand mode, the SDK
makes requests to the API only upon client requests. In polling mode, the SDK
regularly polls the API. Defaults: on-demand. Available options: on-demand, polling.
language
- determines the language for the output. Defaults: en. Available
options and more info see here.
units
- determines the units of measurements for the output. Defaults:
metric. Available options and more info see
here.
cache_size
- determines the number of stored locations in cache. Defaults: 10.
ttl
- determines the Time-To-Live of information in cache (in secs). Defaults:
600.
Each client has its own cache, defined by the number of stored locations and the Time-To-Live (TTL) of the information. In polling mode, the TTL determines the API polling interval.
Note, that polling works only for current weather reaquests! All other requests operate in 'on-demand' mode regardless of the mode selected during client initialization.
This section is actual for versions from 1.0.0. For older versions, see the outdated weather requests section.
Starting from version 1.0.0, the following requests are available:
- current weather
- 5 days weather forecast data with 3-hour step
- hourly weather forecast for 4 days
- 16 days weather forecast
- 30 days weather forecast
- current air pollution
- hourly air pollution forecast for 4 days
- historical air pollution data
- health check
Returns current weather in a specified location. The location can be provided either as a combination of city name, state code (for the US), and country code separated by commas, or as a combination of zip/post code and country code separated by commas.
Please ensure the usage of ISO 3166 country codes.
Args:
location
(str, optional): city name, state code (only for the US) and country code divided by comma.
zip_code
(str, optional): zip/post code and country code divided by comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(zip_code="75007,FR")
See exemple onopenweathermap.org.
Returns 5 days weather forecast data with 3-hour step at specified location. The location can be provided either as a combination of city name, state code (for the US), and country code separated by commas, or as a combination of zip/post code and country code separated by commas.
Please ensure the usage of ISO 3166 country codes.
Args:
location
(str, optional): city name, state code (only for the US) and country code divided by comma.
zip_code
(str, optional): zip/post code and country code divided by comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_5_days(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_5_days(zip_code="75007,FR")
See exemple on openweathermap.org.
Returns hourly weather forecast for 4 days (96 timestamps) at specified location. The location can be provided either as a combination of city name, state code (for the US), and country code separated by commas, or as a combination of zip/post code and country code separated by commas.
Please ensure the usage of ISO 3166 country codes.
Accessible with a "Developer" subscription and higher. See: https://openweathermap.org/full-price.
Args:
location
(str, optional): city name, state code (only for the US) and country code divided by comma.
zip_code
(str, optional): zip/post code and country code divided by comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_hourly(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_hourly(zip_code="75007,FR")
See exemple on openweathermap.org.
Returns 16 days weather forecast data at specified location. The location can be provided either as a combination of city name, state code (for the US), and country code separated by commas, or as a combination of zip/post code and country code separated by commas.
Please ensure the usage of ISO 3166 country codes.
Accessible with a "Startup" subscription and higher. See: https://openweathermap.org/full-price.
Args:
location
(str, optional): city name, state code (only for the US) and country code divided by comma.
zip_code
(str, optional): zip/post code and country code divided by comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_daily_16_days(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_daily_16_days(zip_code="75007,FR")
See exemple on openweathermap.org.
Returns 30 days weather forecast data at specified location. The location can be provided either as a combination of city name, state code (for the US), and country code separated by commas, or as a combination of zip/post code and country code separated by commas.
Please ensure the usage of ISO 3166 country codes.
Accessible with a "Developer" subscription and higher. See: https://openweathermap.org/full-price.
Args:
location
(str, optional): city name, state code (only for the US) and country code divided by comma.
zip_code
(str, optional): zip/post code and country code divided by comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_daily_30_days(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_daily_30_days(zip_code="75007,FR")
See exemple on openweathermap.org.
Returns current air pollution in a specified location. The location can be provided either as a combination of city name, state code (for the US), and country code separated by commas, or as a combination of zip/post code and country code separated by commas.
Please ensure the usage of ISO 3166 country codes.
Args:
location
(str, optional): city name, state code (only for the US) and country code divided by comma.
zip_code
(str, optional): zip/post code and country code divided by comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_air_pollution(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_air_pollution(zip_code="75007,FR")
See exemple on openweathermap.org.
Returns hourly air_pollution forecast for 4 days (96 timestamps) at specified location. The location can be provided either as a combination of city name, state code (for the US), and country code separated by commas, or as a combination of zip/post code and country code separated by commas.
Please ensure the usage of ISO 3166 country codes.
Args:
location
(str, optional): city name, state code (only for the US) and country code divided by comma.
zip_code
(str, optional): zip/post code and country code divided by comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.air_pollution_forecast_hourly(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.air_pollution_forecast_hourly(zip_code="75007,FR")
See exemple on openweathermap.org.
Returns historical air_pollution data at specified location from start data to end. Historical data is accessible from 27th November 2020. The location can be provided either as a combination of city name, state code (for the US), and country code separated by commas, or as a combination of zip/post code and country code separated by commas.
Please ensure the usage of ISO 3166 country codes.
Args:
location
(str, optional): city name, state code (only for the US) and country code divided by comma.
zip_code
(str, optional): zip/post code and country code divided by comma.
start
(int): start date (unix time, UTC time zone), e.g. start=1606488670.
end
(int): end date (unix time, UTC time zone), e.g. end=1606747870.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(zip_code="75007,FR")
See exemple on openweathermap.org.
Returns HTTP response's status.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.health_check()
200
Outdated. Relevant for versions up to 1.0.0!
Available requests for versions from 1.0.0 see here.
Currently, handling requests for current weather by location name or zip code is implemented.
By default, the response is returned in a compact format. You can change this behavior by passing an additional argument.
Compact format has been be deprecated in version 1.0.0!
Also, refer to the example queries.
To request weather by location name, you need to pass the city name as an argument, and optionally the state code (only for the US) and country code, separated by commas.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.get_location_weather("Paris")
The get_location_weather
method has been deprecated in
version 1.0.0.
Starting from version 0.3.2, it is recommended to use the current_weather
method with the city name as an location
argument, and optionally the state
code (only for the US) and country code, separated by commas.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(location="Paris")
Please use ISO 3166 country codes.
To request weather by location name, you need to pass as an argument zip/post code and country code divided by comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.get_zip_weather("75007,FR")
The get_zip_weather
method has been deprecated in
version 1.0.0.
Starting from version 0.3.2, it is recommended to use the current_weather
method with an zip_code
argument zip/post code and country code divided by
comma.
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(zip_code="75007,FR")
Please use ISO 3166 country codes.
compact_mode
- determines whether to return the response in a compact format.
Defaults: True.
The compact_mode
has been deprecated in
version 1.0.0.
The compact_mode
has been deprecated in
version 1.0.0.
{
"weather": {
"main": "Clear",
"description": "clear sky"
},
"temperature": {
"temp": 8.19,
"feels_like": 7.03
},
"visibility": 10000,
"wind": {
"speed": 2.06
},
"datatime": 1710099501,
"sys": {
"sunrise": 1710051241,
"sunset": 1710092882
},
"timezone": 3600,
"name": "Palais-Royal"
}
weather.main
- group of weather parameters (Rain, Snow, Clouds etc.).
weather.description
- weather condition within the group. More info see
here.
temperature.temp
- temperature. Unit Standart: Kelvin, Metric: Celsius,
Imperial: Fahrenheit.
temperature.feels_like
- temperature. This temperature parameter accounts for
the human perception of weather. Unit Standart: Kelvin, Metric: Celsius,
Imperial: Fahrenheit.
visibility
- visibility, meter. The maximum value of the visibility is 10 km.
wind.speed
- wind speed. Unit Standart: meter/sec, Metric: meter/sec,
Imperial: miles/hour.
datatime
- time of data calculation, unix, UTC.
sys.sunrise
- sunrise time, unix, UTC.
sys.sunset
- sunset time, unix, UTC.
timezone
- shift in seconds from UTC.
name
- city name.
{
"coord": {
"lon": 2.32,
"lat": 48.858
},
"weather": [
{
"id": 800,
"main": "Clear",
"description": "clear sky",
"icon": "01n"
}
],
"base": "stations",
"main": {
"temp": 8.19,
"feels_like": 7.03,
"temp_min": 6.07,
"temp_max": 9.42,
"pressure": 998,
"humidity": 86
},
"visibility": 10000,
"wind": {
"speed": 2.06,
"deg": 220
},
"clouds": {
"all": 0
},
"dt": 1710099501,
"sys": {
"type": 2,
"id": 2012208,
"country": "FR",
"sunrise": 1710051241,
"sunset": 1710092882
},
"timezone": 3600,
"id": 6545270,
"name": "Palais-Royal",
"cod": 200
}
Description of full format see here
>>> from openweather_sdk import Client
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.health_check()
200
>>> c.get_location_weather("Paris") # request by location name
{
"weather": {
"main": "Clear",
"description": "clear sky"
},
"temperature": {
"temp": 8.19,
"feels_like": 7.03
},
"visibility": 10000,
"wind": {
"speed": 2.06
},
"datatime": 1710099501,
"sys": {
"sunrise": 1710051241,
"sunset": 1710092882
},
"timezone": 3600,
"name": "Palais-Royal"
}
>>> c.get_location_weather("Paris", compact_mode=False)
{
"coord": {
"lon": 2.32,
"lat": 48.858
},
"weather": [
{
"id": 800,
"main": "Clear",
"description": "clear sky",
"icon": "01n"
}
],
"base": "stations",
"main": {
"temp": 8.19,
"feels_like": 7.03,
"temp_min": 6.07,
"temp_max": 9.42,
"pressure": 998,
"humidity": 86
},
"visibility": 10000,
"wind": {
"speed": 2.06,
"deg": 220
},
"clouds": {
"all": 0
},
"dt": 1710099501,
"sys": {
"type": 2,
"id": 2012208,
"country": "FR",
"sunrise": 1710051241,
"sunset": 1710092882},
"timezone": 3600,
"id": 6545270,
"name": "Palais-Royal",
"cod": 200
}
>>> c.get_zip_weather("75007,FR") # request by zip code
{
'weather': {
'main': 'Clouds',
'description': 'overcast clouds'
},
'temperature': {
'temp': 10.69,
'feels_like': 10.06
},
'visibility': 10000,
'wind': {
'speed': 4.63
},
'datatime': 1710577539,
'sys': {
'sunrise': 1710568880,
'sunset': 1710611823
},
'timezone': 3600,
'name': 'Paris'
}
>>> c.get_zip_weather("75007,FR", compact_mode=False)
{
'coord': {
'lon': 2.3486,
'lat': 48.8534
},
'weather': [
{
'id': 804,
'main': 'Clouds',
'description': 'overcast clouds',
'icon': '04d'
}
],
'base': 'stations',
'main': {
'temp': 10.69,
'feels_like': 10.06,
'temp_min': 10.1,
'temp_max': 11.54,
'pressure': 1021,
'humidity': 86
},
'visibility': 10000,
'wind': {
'speed': 4.63,
'deg': 270
},
'clouds': {
'all': 100
},
'dt': 1710577539,
'sys': {
'type': 2,
'id': 2041230,
'country': 'FR',
'sunrise': 1710568880,
'sunset': 1710611823
},
'timezone': 3600,
'id': 2988507,
'name': 'Paris',
'cod': 200
}
>>> c.remove()
When using logging, be careful: the urllib3
library logs sensitive
information (such as API access tokens) when the DEBUG level is enabled!
To disable logging from the urllib3
library in your project, use this:
import logging
logging.getLogger("urllib3").propagate = False
Description of possible errors can be found on FAQ page ("API errors" section).