SDK for accessing to OpenWeatherAPI
Project description
OpenWeatherSDK
Introduction
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.
Contents
Available requests (for versions from 1.0.0)
Weather request (for versions up to 1.0.0)
Installation
pip install msklv-openweather-sdk
Prerequisites
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").
Client initialization
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.
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.
Cache
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.
Polling mode
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.
Available requests
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
Current weather
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.
Request examples
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(zip_code="75007,FR")
Response
See exemple onopenweathermap.org.
5 days weather forecast
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.
Request examples
>>> 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")
Response
See exemple on openweathermap.org.
Hourly weather forecast
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.
Request examples
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_hourly(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_hourly(zip_code="75007,FR")
Response
See exemple on openweathermap.org.
16 days weather forecast
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.
Request examples
>>> 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")
Response
See exemple on openweathermap.org.
30 days weather forecast
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.
Request examples
>>> 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")
Response
See exemple on openweathermap.org.
Current air pollution
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.
Request examples
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_air_pollution(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_air_pollution(zip_code="75007,FR")
Response
See exemple on openweathermap.org.
Hourly air pollution forecast
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.
Request examples
>>> 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")
Response
See exemple on openweathermap.org.
Historical air pollution data
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.
Request examples
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(location="Paris")
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(zip_code="75007,FR")
Response
See exemple on openweathermap.org.
Health check
Returns HTTP response's status.
Request examples
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.health_check()
Response
200
Outdated weather requests
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.
Weather request by location name
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.
Weather request by zip code
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.
Additional arguments
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.
Description of response formats
Compact format (used by default)
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.
Full format
{
"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
Usage example
>>> 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()
Logging
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
Errors
Description of possible errors can be found on FAQ page ("API errors" section).
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for msklv_openweather_sdk-1.0.0.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | cebeeaa945e56b82b98a9c8bd275350e80a39eba3f5dcd7043d5e2b39d17d6de |
|
| MD5 | f398753718dd71c6f95e937b3e4a165d |
|
| BLAKE2b-256 | 13687d9a43c4c54956578c07714ab5fc5c374a23deeba24bc173554cf5a65b77 |
Hashes for msklv_openweather_sdk-1.0.0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 7e323f495cd1b1747d69a6de395079c2f352d676a419fa648f2cc680e80b207d |
|
| MD5 | c2797bd4e515367ebdbe0d82a6f943f5 |
|
| BLAKE2b-256 | 9b24ec3e2a511fd39008480d8e24f726be220d01cd208c9f24f856c6e411e7cd |
