| Name | msklv-openweather-sdk JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | https://github.com/maskalev/openweather_sdk |
| Summary | SDK for accessing to OpenWeatherAPI |
| upload_time | 2024-04-08 11:52:37 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2024 Aleksandr Maskalev Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
weather
sdk
openweather
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# OpenWeatherSDK
## Introduction
SDK for accessing to [OpenWeatherAPI](https://openweathermap.org/api) 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
[Installation](#installation)
[Prerequisites](#prerequisites)
[Client initialization](#client-initialization)
[Cache](#cache)
[Polling mode](#polling-mode)
[Available requests (for versions from 1.0.0)](#available-requests)
[Weather request (for versions up to 1.0.0)](#weather-request)
[Logging](#logging)
[Errors](#errors)
## Installation
```python
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](https://openweathermap.org/faq)
("Get started" section -> "How to get an API key").
## Client initialization
The only required argument is [the access token](#prerequisites).
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).
### 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](#polling-mode).
`language` - determines the language for the output. Defaults: en. Available
options and more info see [here](https://openweathermap.org/current#multi).
`units` - determines the units of measurements for the output. Defaults:
metric. Available options and more info see
[here](https://openweathermap.org/current#data).
`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](#outdated-weather-requests) section.
Starting from version 1.0.0, the following requests are available:
1. [current weather](#current-weather)
1. [5 days weather forecast data with 3-hour step](#5-days-weather-forecast)
1. [hourly weather forecast for 4 days](#hourly-weather-forecast)
1. [16 days weather forecast](#16-days-weather-forecast)
1. [30 days weather forecast](#30-days-weather-forecast)
1. [current air pollution](#current-air-pollution)
1. [hourly air pollution forecast for 4 days](#hourly-air-pollution-forecast)
1. [historical air pollution data](#historical-air-pollution-data)
1. [health check](#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
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(location="Paris")
```
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(zip_code="75007,FR")
```
#### Response
See exemple on[openweathermap.org](https://openweathermap.org/current#example_JSON).
### 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
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_5_days(location="Paris")
```
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_5_days(zip_code="75007,FR")
```
#### Response
See exemple on [openweathermap.org](https://openweathermap.org/forecast5#example_JSON).
### 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
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_hourly(location="Paris")
```
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_hourly(zip_code="75007,FR")
```
#### Response
See exemple on [openweathermap.org](https://openweathermap.org/api/hourly-forecast#example_JSON).
### 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
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_daily_16_days(location="Paris")
```
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_daily_16_days(zip_code="75007,FR")
```
#### Response
See exemple on [openweathermap.org](https://openweathermap.org/forecast16#example_JSON).
### 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
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_daily_30_days(location="Paris")
```
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.weather_forecast_daily_30_days(zip_code="75007,FR")
```
#### Response
See exemple on [openweathermap.org](https://openweathermap.org/api/forecast30#resp-year).
### 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
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_air_pollution(location="Paris")
```
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_air_pollution(zip_code="75007,FR")
```
#### Response
See exemple on [openweathermap.org](https://openweathermap.org/api/air-pollution#descr).
### 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
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.air_pollution_forecast_hourly(location="Paris")
```
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.air_pollution_forecast_hourly(zip_code="75007,FR")
```
#### Response
See exemple on [openweathermap.org](https://openweathermap.org/api/air-pollution#descr).
### 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
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(location="Paris")
```
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(zip_code="75007,FR")
```
#### Response
See exemple on [openweathermap.org](https://openweathermap.org/api/air-pollution#descr).
### Health check
Returns HTTP response's status.
#### Request examples
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.health_check()
```
#### Response
```python
200
```
## Outdated weather requests
**Outdated. Relevant for versions up to 1.0.0!**
**Available requests for versions from 1.0.0 see [here](#available-requests).**
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](#additional-arguments-1).
Compact format has been be deprecated in
[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased)!
Also, refer to [the example queries](#usage-example).
### 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.
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.get_location_weather("Paris")
```
The `get_location_weather` method has been deprecated in
[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased).
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.
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(location="Paris")
```
Please use
[ISO 3166](https://www.iso.org/iso-3166-country-codes.html) 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.
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.get_zip_weather("75007,FR")
```
The `get_zip_weather` method has been deprecated in
[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased).
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.
```python
>>> c = Client(token=<YOUR_TOKEN>)
>>> c.current_weather(zip_code="75007,FR")
```
Please use
[ISO 3166](https://www.iso.org/iso-3166-country-codes.html) 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](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased).
### Description of response formats
#### Compact format (used by default)
The `compact_mode` has been deprecated in
[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased).
```json
{
"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](https://openweathermap.org/weather-conditions).
`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
```json
{
"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](https://openweathermap.org/current#fields_json)
### Usage example
```python
>>> 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:
```python
import logging
logging.getLogger("urllib3").propagate = False
```
## Errors
Description of possible errors can be found on
[FAQ page](https://openweathermap.org/faq) ("API errors" section).
Raw data
{
"_id": null,
"home_page": "https://github.com/maskalev/openweather_sdk",
"name": "msklv-openweather-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "weather, sdk, openweather",
"author": null,
"author_email": "Aleksandr Maskalev <avmaskalev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/13/68/7d9a43c4c54956578c07714ab5fc5c374a23deeba24bc173554cf5a65b77/msklv_openweather_sdk-1.0.0.tar.gz",
"platform": null,
"description": "# OpenWeatherSDK\n\n## Introduction\n\nSDK for accessing to [OpenWeatherAPI](https://openweathermap.org/api) and\nretrieving information about current weather conditions in a specified city.\nThe SDK can operate in two modes: *on-demand* and *polling*. In *on-demand*\nmode (the default mode), API requests are made on user demand, while in the\n*polling* mode, there is regular polling of the API for weather updates in the\nsaved (previously requested) cities.\n\n## Contents\n\n[Installation](#installation)\n\n[Prerequisites](#prerequisites)\n\n[Client initialization](#client-initialization)\n\n[Cache](#cache)\n\n[Polling mode](#polling-mode)\n\n[Available requests (for versions from 1.0.0)](#available-requests)\n\n[Weather request (for versions up to 1.0.0)](#weather-request)\n\n[Logging](#logging)\n\n[Errors](#errors)\n\n## Installation\n\n```python\npip install msklv-openweather-sdk\n```\n\n## Prerequisites\n\nTo work with the SDK, you need to obtain an access token for OpenWeatherAPI.\nMore information can be found on [FAQ page](https://openweathermap.org/faq)\n(\"Get started\" section -> \"How to get an API key\").\n\n## Client initialization\n\nThe only required argument is [the access token](#prerequisites).\n\nBy default, the SDK operates in on-demand mode, returns information in English,\nuses the metric system of measurements, has a cache size of 10 locations, and\nthe information remains valid for 10 minutes. You can modify this mode by\npassing additional arguments during client initialization.\n\nAdditionally, if you need to modify the behavior of the SDK, you can pass\n[additional arguments](#additional-arguments).\n\n### Additional arguments\n\n`mode` - determines the operating mode of the SDK. In on-demand mode, the SDK\nmakes requests to the API only upon client requests. In polling mode, the SDK\nregularly polls the API. Defaults: on-demand. Available options: on-demand, [polling](#polling-mode).\n\n`language` - determines the language for the output. Defaults: en. Available\noptions and more info see [here](https://openweathermap.org/current#multi).\n\n`units` - determines the units of measurements for the output. Defaults:\nmetric. Available options and more info see\n[here](https://openweathermap.org/current#data).\n\n`cache_size` - determines the number of stored locations in cache. Defaults: 10.\n\n`ttl` - determines the Time-To-Live of information in cache (in secs). Defaults:\n600. \n\n## Cache\n\nEach client has its own cache, defined by the number of stored locations and\nthe Time-To-Live (TTL) of the information. In polling mode, the TTL determines\nthe API polling interval.\n\n## Polling mode\n\nNote, that polling works only for current weather reaquests!\nAll other requests operate in 'on-demand' mode regardless of the mode selected\nduring client initialization.\n\n## Available requests\n\nThis section is actual for versions from 1.0.0. For older versions, see the\n[outdated weather requests](#outdated-weather-requests) section.\n\nStarting from version 1.0.0, the following requests are available:\n\n1. [current weather](#current-weather)\n1. [5 days weather forecast data with 3-hour step](#5-days-weather-forecast)\n1. [hourly weather forecast for 4 days](#hourly-weather-forecast)\n1. [16 days weather forecast](#16-days-weather-forecast)\n1. [30 days weather forecast](#30-days-weather-forecast)\n1. [current air pollution](#current-air-pollution)\n1. [hourly air pollution forecast for 4 days](#hourly-air-pollution-forecast)\n1. [historical air pollution data](#historical-air-pollution-data)\n1. [health check](#health-check)\n\n### Current weather\n\nReturns current weather in a specified location.\nThe location can be provided either as a combination of city name,\nstate code (for the US), and country code separated by commas, or\nas a combination of zip/post code and country code separated by commas.\n\nPlease ensure the usage of ISO 3166 country codes.\n\nArgs:\n\n`location` *(str, optional)*: city name, state code (only for the US) and country code divided by comma.\n\n`zip_code` *(str, optional)*: zip/post code and country code divided by comma.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.current_weather(location=\"Paris\")\n```\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.current_weather(zip_code=\"75007,FR\")\n```\n\n#### Response\n\nSee exemple on[openweathermap.org](https://openweathermap.org/current#example_JSON).\n\n### 5 days weather forecast\n\nReturns 5 days weather forecast data with 3-hour step at specified location.\nThe location can be provided either as a combination of city name,\nstate code (for the US), and country code separated by commas, or\nas a combination of zip/post code and country code separated by commas.\n\nPlease ensure the usage of ISO 3166 country codes.\n\nArgs:\n\n`location` *(str, optional)*: city name, state code (only for the US) and country code divided by comma.\n\n`zip_code` *(str, optional)*: zip/post code and country code divided by comma.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.weather_forecast_5_days(location=\"Paris\")\n```\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.weather_forecast_5_days(zip_code=\"75007,FR\")\n```\n\n#### Response\n\nSee exemple on [openweathermap.org](https://openweathermap.org/forecast5#example_JSON).\n\n### Hourly weather forecast\n\nReturns hourly weather forecast for 4 days (96 timestamps) at specified location.\nThe location can be provided either as a combination of city name,\nstate code (for the US), and country code separated by commas, or\nas a combination of zip/post code and country code separated by commas.\n\nPlease ensure the usage of ISO 3166 country codes.\n\nAccessible with a \"Developer\" subscription and higher. See: https://openweathermap.org/full-price.\n\nArgs:\n\n`location` *(str, optional)*: city name, state code (only for the US) and country code divided by comma.\n\n`zip_code` *(str, optional)*: zip/post code and country code divided by comma.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.weather_forecast_hourly(location=\"Paris\")\n```\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.weather_forecast_hourly(zip_code=\"75007,FR\")\n```\n\n#### Response\n\nSee exemple on [openweathermap.org](https://openweathermap.org/api/hourly-forecast#example_JSON).\n\n### 16 days weather forecast\n\nReturns 16 days weather forecast data at specified location.\nThe location can be provided either as a combination of city name,\nstate code (for the US), and country code separated by commas, or\nas a combination of zip/post code and country code separated by commas.\n\nPlease ensure the usage of ISO 3166 country codes.\n\nAccessible with a \"Startup\" subscription and higher. See: https://openweathermap.org/full-price.\n\nArgs:\n\n`location` *(str, optional)*: city name, state code (only for the US) and country code divided by comma.\n\n`zip_code` *(str, optional)*: zip/post code and country code divided by comma.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.weather_forecast_daily_16_days(location=\"Paris\")\n```\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.weather_forecast_daily_16_days(zip_code=\"75007,FR\")\n```\n\n#### Response\n\nSee exemple on [openweathermap.org](https://openweathermap.org/forecast16#example_JSON).\n\n### 30 days weather forecast\n\nReturns 30 days weather forecast data at specified location.\nThe location can be provided either as a combination of city name,\nstate code (for the US), and country code separated by commas, or\nas a combination of zip/post code and country code separated by commas.\n\nPlease ensure the usage of ISO 3166 country codes.\n\nAccessible with a \"Developer\" subscription and higher. See: https://openweathermap.org/full-price.\n\nArgs:\n\n`location` *(str, optional)*: city name, state code (only for the US) and country code divided by comma.\n\n`zip_code` *(str, optional)*: zip/post code and country code divided by comma.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.weather_forecast_daily_30_days(location=\"Paris\")\n```\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.weather_forecast_daily_30_days(zip_code=\"75007,FR\")\n```\n\n#### Response\n\nSee exemple on [openweathermap.org](https://openweathermap.org/api/forecast30#resp-year).\n\n### Current air pollution\n\nReturns current air pollution in a specified location.\nThe location can be provided either as a combination of city name,\nstate code (for the US), and country code separated by commas, or\nas a combination of zip/post code and country code separated by commas.\n\nPlease ensure the usage of ISO 3166 country codes.\n\nArgs:\n\n`location` *(str, optional)*: city name, state code (only for the US) and country code divided by comma.\n\n`zip_code` *(str, optional)*: zip/post code and country code divided by comma.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.current_air_pollution(location=\"Paris\")\n```\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.current_air_pollution(zip_code=\"75007,FR\")\n```\n\n#### Response\n\nSee exemple on [openweathermap.org](https://openweathermap.org/api/air-pollution#descr).\n\n### Hourly air pollution forecast\n\nReturns hourly air_pollution forecast for 4 days (96 timestamps) at specified location.\nThe location can be provided either as a combination of city name,\nstate code (for the US), and country code separated by commas, or\nas a combination of zip/post code and country code separated by commas.\n\nPlease ensure the usage of ISO 3166 country codes.\n\nArgs:\n\n`location` *(str, optional)*: city name, state code (only for the US) and country code divided by comma.\n\n`zip_code` *(str, optional)*: zip/post code and country code divided by comma.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.air_pollution_forecast_hourly(location=\"Paris\")\n```\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.air_pollution_forecast_hourly(zip_code=\"75007,FR\")\n```\n\n#### Response\n\nSee exemple on [openweathermap.org](https://openweathermap.org/api/air-pollution#descr).\n \n### Historical air pollution data\n\nReturns historical air_pollution data at specified location from start data to end.\nHistorical data is accessible from 27th November 2020.\nThe location can be provided either as a combination of city name,\nstate code (for the US), and country code separated by commas, or\nas a combination of zip/post code and country code separated by commas.\n\nPlease ensure the usage of ISO 3166 country codes.\n\nArgs:\n\n`location` *(str, optional)*: city name, state code (only for the US) and country code divided by comma.\n\n`zip_code` *(str, optional)*: zip/post code and country code divided by comma.\n\n`start` *(int)*: start date (unix time, UTC time zone), e.g. start=1606488670.\n\n`end` *(int)*: end date (unix time, UTC time zone), e.g. end=1606747870.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.current_weather(location=\"Paris\")\n```\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.current_weather(zip_code=\"75007,FR\")\n```\n\n#### Response\n\nSee exemple on [openweathermap.org](https://openweathermap.org/api/air-pollution#descr).\n\n### Health check\n\nReturns HTTP response's status.\n\n#### Request examples\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.health_check()\n```\n\n#### Response\n\n```python\n200\n```\n\n## Outdated weather requests\n\n**Outdated. Relevant for versions up to 1.0.0!**\n\n**Available requests for versions from 1.0.0 see [here](#available-requests).**\n\nCurrently, handling requests for current weather by location name or zip code is\nimplemented.\n\nBy default, the response is returned in a compact format. You can change this\nbehavior by passing an [additional argument](#additional-arguments-1).\n\nCompact format has been be deprecated in\n[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased)!\n\nAlso, refer to [the example queries](#usage-example).\n\n### Weather request by location name\n\nTo request weather by location name, you need to pass the city name as an \nargument, and optionally the state code (only for the US) and country code, \nseparated by commas. \n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.get_location_weather(\"Paris\")\n```\n\nThe `get_location_weather` method has been deprecated in\n[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased).\n\nStarting from version 0.3.2, it is recommended to use the `current_weather`\nmethod with the city name as an `location` argument, and optionally the state\ncode (only for the US) and country code, separated by commas.\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.current_weather(location=\"Paris\")\n```\n\nPlease use\n[ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country codes.\n\n### Weather request by zip code\n\nTo request weather by location name, you need to pass as an argument zip/post \ncode and country code divided by comma.\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.get_zip_weather(\"75007,FR\")\n```\n\nThe `get_zip_weather` method has been deprecated in\n[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased).\n\nStarting from version 0.3.2, it is recommended to use the `current_weather`\nmethod with an `zip_code` argument zip/post code and country code divided by\ncomma.\n\n```python\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.current_weather(zip_code=\"75007,FR\")\n```\n\nPlease use\n[ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country codes.\n\n### Additional arguments\n\n`compact_mode` - determines whether to return the response in a compact format.\nDefaults: True.\n\nThe `compact_mode` has been deprecated in\n[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased).\n\n### Description of response formats\n\n#### Compact format (used by default)\n\nThe `compact_mode` has been deprecated in\n[version 1.0.0](https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md#unreleased).\n\n\n```json\n{\n \"weather\": {\n \"main\": \"Clear\",\n \"description\": \"clear sky\"\n }, \n \"temperature\": {\n \"temp\": 8.19,\n \"feels_like\": 7.03\n }, \n \"visibility\": 10000, \n \"wind\": {\n \"speed\": 2.06\n }, \n \"datatime\": 1710099501, \n \"sys\": {\n \"sunrise\": 1710051241,\n \"sunset\": 1710092882\n }, \n \"timezone\": 3600, \n \"name\": \"Palais-Royal\"\n}\n```\n\n`weather.main` - group of weather parameters (Rain, Snow, Clouds etc.).\n\n`weather.description` - weather condition within the group. More info see\n[here](https://openweathermap.org/weather-conditions).\n\n`temperature.temp` - temperature. Unit Standart: Kelvin, Metric: Celsius,\nImperial: Fahrenheit.\n\n`temperature.feels_like` - temperature. This temperature parameter accounts for\nthe human perception of weather. Unit Standart: Kelvin, Metric: Celsius,\nImperial: Fahrenheit.\n\n`visibility` - visibility, meter. The maximum value of the visibility is 10 km.\n\n`wind.speed` - wind speed. Unit Standart: meter/sec, Metric: meter/sec,\nImperial: miles/hour.\n\n`datatime` - time of data calculation, unix, UTC.\n\n`sys.sunrise` - sunrise time, unix, UTC.\n\n`sys.sunset` - sunset time, unix, UTC.\n\n`timezone` - shift in seconds from UTC.\n\n`name` - city name.\n\n#### Full format\n\n```json\n{\n \"coord\": {\n \"lon\": 2.32,\n \"lat\": 48.858\n },\n \"weather\": [\n {\n \"id\": 800,\n \"main\": \"Clear\",\n \"description\": \"clear sky\",\n \"icon\": \"01n\"\n }\n ],\n \"base\": \"stations\",\n \"main\": {\n \"temp\": 8.19,\n \"feels_like\": 7.03,\n \"temp_min\": 6.07,\n \"temp_max\": 9.42,\n \"pressure\": 998,\n \"humidity\": 86\n },\n \"visibility\": 10000,\n \"wind\": {\n \"speed\": 2.06,\n \"deg\": 220\n },\n \"clouds\": {\n \"all\": 0\n },\n \"dt\": 1710099501,\n \"sys\": {\n \"type\": 2,\n \"id\": 2012208,\n \"country\": \"FR\",\n \"sunrise\": 1710051241,\n \"sunset\": 1710092882\n },\n \"timezone\": 3600,\n \"id\": 6545270,\n \"name\": \"Palais-Royal\",\n \"cod\": 200\n}\n```\n\nDescription of full format see\n[here](https://openweathermap.org/current#fields_json)\n\n### Usage example\n\n```python\n>>> from openweather_sdk import Client\n>>> c = Client(token=<YOUR_TOKEN>)\n>>> c.health_check()\n200\n>>> c.get_location_weather(\"Paris\") # request by location name\n{\n \"weather\": {\n \"main\": \"Clear\",\n \"description\": \"clear sky\"\n }, \n \"temperature\": {\n \"temp\": 8.19,\n \"feels_like\": 7.03\n }, \n \"visibility\": 10000, \n \"wind\": {\n \"speed\": 2.06\n }, \n \"datatime\": 1710099501, \n \"sys\": {\n \"sunrise\": 1710051241,\n \"sunset\": 1710092882\n }, \n \"timezone\": 3600, \n \"name\": \"Palais-Royal\"\n}\n>>> c.get_location_weather(\"Paris\", compact_mode=False)\n{\n \"coord\": {\n \"lon\": 2.32,\n \"lat\": 48.858\n },\n \"weather\": [\n {\n \"id\": 800,\n \"main\": \"Clear\",\n \"description\": \"clear sky\",\n \"icon\": \"01n\"\n }\n ],\n \"base\": \"stations\",\n \"main\": {\n \"temp\": 8.19,\n \"feels_like\": 7.03,\n \"temp_min\": 6.07,\n \"temp_max\": 9.42,\n \"pressure\": 998,\n \"humidity\": 86\n },\n \"visibility\": 10000,\n \"wind\": {\n \"speed\": 2.06,\n \"deg\": 220\n },\n \"clouds\": {\n \"all\": 0\n },\n \"dt\": 1710099501,\n \"sys\": {\n \"type\": 2,\n \"id\": 2012208,\n \"country\": \"FR\",\n \"sunrise\": 1710051241,\n \"sunset\": 1710092882},\n \"timezone\": 3600,\n \"id\": 6545270,\n \"name\": \"Palais-Royal\",\n \"cod\": 200\n}\n>>> c.get_zip_weather(\"75007,FR\") # request by zip code\n{\n 'weather': {\n 'main': 'Clouds',\n 'description': 'overcast clouds'\n },\n 'temperature': {\n 'temp': 10.69,\n 'feels_like': 10.06\n },\n 'visibility': 10000,\n 'wind': {\n 'speed': 4.63\n },\n 'datatime': 1710577539,\n 'sys': {\n 'sunrise': 1710568880,\n 'sunset': 1710611823\n },\n 'timezone': 3600,\n 'name': 'Paris'\n}\n>>> c.get_zip_weather(\"75007,FR\", compact_mode=False)\n{\n 'coord': {\n 'lon': 2.3486,\n 'lat': 48.8534\n },\n 'weather': [\n {\n 'id': 804,\n 'main': 'Clouds',\n 'description': 'overcast clouds',\n 'icon': '04d'\n }\n ],\n 'base': 'stations',\n 'main': {\n 'temp': 10.69,\n 'feels_like': 10.06,\n 'temp_min': 10.1,\n 'temp_max': 11.54,\n 'pressure': 1021,\n 'humidity': 86\n },\n 'visibility': 10000,\n 'wind': {\n 'speed': 4.63,\n 'deg': 270\n },\n 'clouds': {\n 'all': 100\n },\n 'dt': 1710577539,\n 'sys': {\n 'type': 2,\n 'id': 2041230,\n 'country': 'FR',\n 'sunrise': 1710568880,\n 'sunset': 1710611823\n },\n 'timezone': 3600,\n 'id': 2988507,\n 'name': 'Paris',\n 'cod': 200\n}\n>>> c.remove()\n```\n\n## Logging\n\nWhen using logging, be careful: the `urllib3` library logs sensitive\ninformation (such as API access tokens) when the DEBUG level is enabled!\n\nTo disable logging from the `urllib3` library in your project, use this:\n\n```python\nimport logging\nlogging.getLogger(\"urllib3\").propagate = False\n```\n\n## Errors\n\nDescription of possible errors can be found on\n[FAQ page](https://openweathermap.org/faq) (\"API errors\" section).\n\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Aleksandr Maskalev Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "SDK for accessing to OpenWeatherAPI",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/maskalev/openweather_sdk/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/maskalev/openweather_sdk"
},
"split_keywords": [
"weather",
" sdk",
" openweather"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9b24ec3e2a511fd39008480d8e24f726be220d01cd208c9f24f856c6e411e7cd",
"md5": "c2797bd4e515367ebdbe0d82a6f943f5",
"sha256": "7e323f495cd1b1747d69a6de395079c2f352d676a419fa648f2cc680e80b207d"
},
"downloads": -1,
"filename": "msklv_openweather_sdk-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2797bd4e515367ebdbe0d82a6f943f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18043,
"upload_time": "2024-04-08T11:52:35",
"upload_time_iso_8601": "2024-04-08T11:52:35.846052Z",
"url": "https://files.pythonhosted.org/packages/9b/24/ec3e2a511fd39008480d8e24f726be220d01cd208c9f24f856c6e411e7cd/msklv_openweather_sdk-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "13687d9a43c4c54956578c07714ab5fc5c374a23deeba24bc173554cf5a65b77",
"md5": "f398753718dd71c6f95e937b3e4a165d",
"sha256": "cebeeaa945e56b82b98a9c8bd275350e80a39eba3f5dcd7043d5e2b39d17d6de"
},
"downloads": -1,
"filename": "msklv_openweather_sdk-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "f398753718dd71c6f95e937b3e4a165d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17571,
"upload_time": "2024-04-08T11:52:37",
"upload_time_iso_8601": "2024-04-08T11:52:37.555793Z",
"url": "https://files.pythonhosted.org/packages/13/68/7d9a43c4c54956578c07714ab5fc5c374a23deeba24bc173554cf5a65b77/msklv_openweather_sdk-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-08 11:52:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maskalev",
"github_project": "openweather_sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "msklv-openweather-sdk"
}
