Metadata-Version: 2.1
Name: gfz_api_client
Version: 0.0.5
Summary: GFZ Helmholtz Centre for Geosciences Web Service API Client
Home-page: https://github.com/mmatroskin/gfz_api_client
Author: Maksim Tulin
Project-URL: Source, https://github.com/mmatroskin/gfz_api_client
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp <4.0,>=3.8
Requires-Dist: requests <3.0.0,>=2.0.0
Requires-Dist: ujson <6.0,>=5.0

# GFZ Helmholtz Centre for Geosciences Web Service API Client

## Description

Unofficial client for **Helmholtz Centre for Geosciences** Web Service API. For getting Geomagnetic Index (Kp, etc) 
Nowcast and Forecast data (https://spaceweather.gfz-potsdam.de/products-data/forecasts/forecast-kp-index). 
Kp is an important measure for the energy input from the solar wind to Earth and it is used by space weather services in near real-time. 
The geomagnetic Hpo index is a Kp-like index with a time resolution of half an hour, called Hp30, and one hour, called Hp60.

Official API description : https://kp.gfz-potsdam.de/en/data

***Python 3.10+ requires***

## Features

- Getting geomagnetic index forecast (as a Dict)
- Getting geomagnetic three-hourly index for period (as a Dict)
- Getting geomagnetic three-hourly index for period as a Tuple (like an official client by GFZ German Research Centre for Geosciences)

## Classes

Library provides Classic and Asynchronous client classes for using in python applications:

**GFZClient** - Classic client class for Web Service API

**GFZAsyncClient** - Asynchronous client class for Web Service API

## Methods

### get_forecast(index)

Returns Dict with Index prediction dataset. 
Parameter `index` define index for data request. Should be in `('Kp','Hp30', 'Hp30')`

### get_nowcast(start_time, end_time, index, [data_state])

Returns Dict with geomagnetic three-hourly Index for period. 
Parameters `start_time` and `end_time` defines time period. Both should be string with UTC date/time, format: `'YYYY-MM-DD'` or `'YYYY-MM-DDThh:mm:ss'`
Parameter `index` define index for data request. Should be in `('Kp', 'ap', 'Ap', 'Cp', 'C9', 'Hp30', 'Hp60', 'ap30', 'ap60', 'SN', 'Fobs', 'Fadj')`
Optional Parameter `data_state` define index state. Possible values: `'def', 'all'`. Output of definitive values only (only for **Kp, ap, Ap, Cp, C9, SN**) 

### get_kp_index(starttime, endtime, index, [status])

Returns tuple with geomagnetic three-hourly Index for period or `(0, 0, 0)` in an Error case. 
Parameters `starttime` and `endtime` defines time period. Both should be string with UTC date/time, format: `'YYYY-MM-DD'` or `'YYYY-MM-DDThh:mm:ss'`
Parameter `index` define index for data request. Should be in `('Kp', 'ap', 'Ap', 'Cp', 'C9', 'Hp30', 'Hp60', 'ap30', 'ap60', 'SN', 'Fobs', 'Fadj')`
Optional Parameter `status` define index state. Possible values: `'def', 'all'`. Output of definitive values only (only for **Kp, ap, Ap, Cp, C9, SN**)

Method **get_kp_index** implements getKpindex method from official python client with same behaviour and added for compatibility purposes

## How to use

### Installation

```shell
pip install gfz-api-client
```

### Classic client

```python
from gfz_client import GFZClient

client = GFZClient()

# Get geomagnetic index forecast
data = client.get_forecast(index="Kp")

# Get geomagnetic three-hourly Kp index for period
data = client.get_nowcast(start_time="2011-11-04T00:05:23", end_time="2011-11-04T00:05:23", index="Kp")

# Get geomagnetic three-hourly Kp index for period as a tuple
data = client.get_kp_index(starttime="2011-11-04T00:05:23Z", endtime="2011-11-04T00:05:23Z", index="Kp")

```

### Asynchronous client

```python
from gfz_client import GFZAsyncClient

client = GFZAsyncClient()

# Get geomagnetic index forecast
data = await client.get_forecast(index="Kp")

# Get geomagnetic three-hourly Kp index for period
data = await client.get_nowcast(start_time="2011-11-04T00:05:23Z", end_time="2011-11-04T00:05:23Z", index="Kp")

# Get geomagnetic three-hourly Kp index for period as a tuple
data = await client.get_kp_index(starttime="2011-11-04T00:05:23", endtime="2011-11-04T00:05:23", index="Kp")

```
