jiskta 0.5.0__tar.gz

jiskta-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiskta
+
+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.

jiskta-0.5.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: jiskta
+Version: 0.5.0
+Summary: Python SDK for the Jiskta Climate Data API
+License: MIT
+Project-URL: Homepage, https://jiskta.com
+Project-URL: Documentation, https://jiskta.com/docs
+Project-URL: Repository, https://github.com/jiskta/jiskta-python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Dynamic: license-file
+
+# jiskta-python
+
+Python SDK for the [Jiskta Climate Data API](https://jiskta.com) — query historical air quality data (NO₂, PM2.5, PM10, O₃) and ERA5 meteorological data via a simple Python interface.
+
+## Install
+
+```bash
+pip install git+https://github.com/jiskta/jiskta-python.git
+```
+
+Pandas is optional but recommended:
+```bash
+pip install "git+https://github.com/jiskta/jiskta-python.git#egg=jiskta[pandas]"
+```
+
+## Quick start
+
+```python
+from jiskta import JisktaClient
+
+client = JisktaClient(api_key="sk_live_...")
+
+# Daily NO₂ and PM2.5 over Paris in 2023
+df = client.query(
+    lat=(48.7, 49.0),
+    lon=(2.2, 2.5),
+    start="2023-01",
+    end="2023-12",
+    variables=["no2", "pm2p5"],
+    aggregate="daily",
+)
+print(df.head())
+#         lat    lon        date  no2_mean  pm2p5_mean
+# 0  48.7500  2.250  2023-01-01     12.34        8.21
+# ...
+```
+
+## All parameters
+
+```python
+df = client.query(
+    lat=(lat_min, lat_max),      # bounding box
+    lon=(lon_min, lon_max),
+    start="YYYY-MM-DD",          # or "YYYY-MM"
+    end="YYYY-MM-DD",
+    variables=["no2"],          # no2 | pm2p5 | pm10 | o3
+    aggregate="daily",           # hourly | daily | monthly | annual
+                                 # area_hourly | area_daily | area_monthly
+                                 # diurnal | exceedance | percentile
+    threshold=40.0,              # µg/m³  (exceedance mode)
+    percentile=95,               # 0-100  (percentile mode)
+)
+```
+
+## Summary statistics (no DataFrame)
+
+```python
+result = client.stats(
+    lat=(48.7, 49.0),
+    lon=(2.2, 2.5),
+    start="2023-01",
+    end="2023-01",
+    variables=["no2"],
+)
+print(result["output"])
+```
+
+## Error handling
+
+```python
+from jiskta import JisktaClient, AuthError, InsufficientCreditsError, RateLimitError, JisktaError
+
+try:
+    df = client.query(...)
+except AuthError:
+    print("Invalid API key")
+except InsufficientCreditsError:
+    print("Buy more credits at https://jiskta.com/pricing")
+except RateLimitError:
+    print("Server busy, retry later")
+except JisktaError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Named area queries
+
+Skip lat/lon by passing a named region:
+
+```python
+df = client.query(
+    area="paris",
+    start="2023-01",
+    end="2023-12",
+    variables=["no2"],
+    aggregate="daily",
+)
+
+result = client.stats(area="belgium", start="2023-01", end="2023-12")
+```
+
+Supported names depend on the API (e.g. `"paris"`, `"france"`, `"belgium"`).
+
+## New aggregates
+
+```python
+# Statistical aggregates
+df = client.query(..., aggregate="max")       # daily/monthly max
+df = client.query(..., aggregate="min")       # daily/monthly min
+df = client.query(..., aggregate="stddev")    # standard deviation
+df = client.query(..., aggregate="cumulative")  # running total (e.g. precipitation)
+
+# Analytical aggregates
+df = client.query(..., aggregate="seasonal")  # DJF/MAM/JJA/SON means
+df = client.query(..., aggregate="trend")     # linear trend per grid cell
+```
+
+## Wind variables
+
+`wind_speed` and `wind_dir` are derived ERA5 variables (computed from `u10`/`v10`):
+
+```python
+df = client.query(
+    lat=(48.7, 49.0), lon=(2.2, 2.5),
+    start="2023-01", end="2023-12",
+    variables=["wind_speed", "wind_dir"],
+    aggregate="daily",
+)
+```
+
+## Polygon-masked queries
+
+Pass any GeoJSON `Polygon` or `MultiPolygon` geometry to restrict results to cells
+whose centres fall inside the polygon:
+
+```python
+mask = {
+    "type": "Polygon",
+    "coordinates": [[[2.2, 48.7], [2.5, 48.7], [2.5, 49.0], [2.2, 49.0], [2.2, 48.7]]],
+}
+
+df = client.query_with_mask(
+    lat_min=48.7, lat_max=49.0,
+    lon_min=2.2, lon_max=2.5,
+    start="2023-01",
+    end="2023-12",
+    variables=["no2"],
+    aggregate="daily",
+    mask=mask,
+)
+```
+
+## Advanced options
+
+```python
+df = client.query(
+    lat=(48.7, 49.0), lon=(2.2, 2.5),
+    start="2023-01", end="2023-12",
+    variables=["no2"],
+    sort_by="no2_mean",       # sort CSV output by column
+    sort_dir="desc",          # "asc" or "desc"
+    unit="ppb",               # convert output units
+    round=2,                  # decimal places
+    dry_run=True,             # cost estimate only — no query executed
+    missing_null=True,        # empty string for missing cells
+    include_polygon=True,     # include area_polygon GeoJSON in raw response
+)
+```
+
+## License
+
+MIT

jiskta-0.5.0/README.md

@@ -0,0 +1,171 @@
+# jiskta-python
+
+Python SDK for the [Jiskta Climate Data API](https://jiskta.com) — query historical air quality data (NO₂, PM2.5, PM10, O₃) and ERA5 meteorological data via a simple Python interface.
+
+## Install
+
+```bash
+pip install git+https://github.com/jiskta/jiskta-python.git
+```
+
+Pandas is optional but recommended:
+```bash
+pip install "git+https://github.com/jiskta/jiskta-python.git#egg=jiskta[pandas]"
+```
+
+## Quick start
+
+```python
+from jiskta import JisktaClient
+
+client = JisktaClient(api_key="sk_live_...")
+
+# Daily NO₂ and PM2.5 over Paris in 2023
+df = client.query(
+    lat=(48.7, 49.0),
+    lon=(2.2, 2.5),
+    start="2023-01",
+    end="2023-12",
+    variables=["no2", "pm2p5"],
+    aggregate="daily",
+)
+print(df.head())
+#         lat    lon        date  no2_mean  pm2p5_mean
+# 0  48.7500  2.250  2023-01-01     12.34        8.21
+# ...
+```
+
+## All parameters
+
+```python
+df = client.query(
+    lat=(lat_min, lat_max),      # bounding box
+    lon=(lon_min, lon_max),
+    start="YYYY-MM-DD",          # or "YYYY-MM"
+    end="YYYY-MM-DD",
+    variables=["no2"],          # no2 | pm2p5 | pm10 | o3
+    aggregate="daily",           # hourly | daily | monthly | annual
+                                 # area_hourly | area_daily | area_monthly
+                                 # diurnal | exceedance | percentile
+    threshold=40.0,              # µg/m³  (exceedance mode)
+    percentile=95,               # 0-100  (percentile mode)
+)
+```
+
+## Summary statistics (no DataFrame)
+
+```python
+result = client.stats(
+    lat=(48.7, 49.0),
+    lon=(2.2, 2.5),
+    start="2023-01",
+    end="2023-01",
+    variables=["no2"],
+)
+print(result["output"])
+```
+
+## Error handling
+
+```python
+from jiskta import JisktaClient, AuthError, InsufficientCreditsError, RateLimitError, JisktaError
+
+try:
+    df = client.query(...)
+except AuthError:
+    print("Invalid API key")
+except InsufficientCreditsError:
+    print("Buy more credits at https://jiskta.com/pricing")
+except RateLimitError:
+    print("Server busy, retry later")
+except JisktaError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Named area queries
+
+Skip lat/lon by passing a named region:
+
+```python
+df = client.query(
+    area="paris",
+    start="2023-01",
+    end="2023-12",
+    variables=["no2"],
+    aggregate="daily",
+)
+
+result = client.stats(area="belgium", start="2023-01", end="2023-12")
+```
+
+Supported names depend on the API (e.g. `"paris"`, `"france"`, `"belgium"`).
+
+## New aggregates
+
+```python
+# Statistical aggregates
+df = client.query(..., aggregate="max")       # daily/monthly max
+df = client.query(..., aggregate="min")       # daily/monthly min
+df = client.query(..., aggregate="stddev")    # standard deviation
+df = client.query(..., aggregate="cumulative")  # running total (e.g. precipitation)
+
+# Analytical aggregates
+df = client.query(..., aggregate="seasonal")  # DJF/MAM/JJA/SON means
+df = client.query(..., aggregate="trend")     # linear trend per grid cell
+```
+
+## Wind variables
+
+`wind_speed` and `wind_dir` are derived ERA5 variables (computed from `u10`/`v10`):
+
+```python
+df = client.query(
+    lat=(48.7, 49.0), lon=(2.2, 2.5),
+    start="2023-01", end="2023-12",
+    variables=["wind_speed", "wind_dir"],
+    aggregate="daily",
+)
+```
+
+## Polygon-masked queries
+
+Pass any GeoJSON `Polygon` or `MultiPolygon` geometry to restrict results to cells
+whose centres fall inside the polygon:
+
+```python
+mask = {
+    "type": "Polygon",
+    "coordinates": [[[2.2, 48.7], [2.5, 48.7], [2.5, 49.0], [2.2, 49.0], [2.2, 48.7]]],
+}
+
+df = client.query_with_mask(
+    lat_min=48.7, lat_max=49.0,
+    lon_min=2.2, lon_max=2.5,
+    start="2023-01",
+    end="2023-12",
+    variables=["no2"],
+    aggregate="daily",
+    mask=mask,
+)
+```
+
+## Advanced options
+
+```python
+df = client.query(
+    lat=(48.7, 49.0), lon=(2.2, 2.5),
+    start="2023-01", end="2023-12",
+    variables=["no2"],
+    sort_by="no2_mean",       # sort CSV output by column
+    sort_dir="desc",          # "asc" or "desc"
+    unit="ppb",               # convert output units
+    round=2,                  # decimal places
+    dry_run=True,             # cost estimate only — no query executed
+    missing_null=True,        # empty string for missing cells
+    include_polygon=True,     # include area_polygon GeoJSON in raw response
+)
+```
+
+## License
+
+MIT

jiskta-0.5.0/jiskta/__init__.py

@@ -0,0 +1,31 @@
+"""
+Jiskta Python SDK
+~~~~~~~~~~~~~~~~~
+
+Simple client for the Jiskta Climate Data API.
+https://jiskta.com/docs
+
+Usage::
+
+    from jiskta import JisktaClient
+
+    client = JisktaClient(api_key="sk_live_...")
+    df = client.query(
+        lat=(48.0, 49.0),
+        lon=(2.0, 3.0),
+        start="2023-01",
+        end="2023-12",
+        variables=["no2", "pm2p5"],
+    )
+    print(df.head())
+"""
+
+from .client import JisktaClient, Variable, CamsVariable, Era5Variable, Aggregate
+from .exceptions import JisktaError, AuthError, InsufficientCreditsError, RateLimitError
+
+__version__ = "0.5.0"
+__all__ = [
+    "JisktaClient",
+    "Variable", "CamsVariable", "Era5Variable", "Aggregate",
+    "JisktaError", "AuthError", "InsufficientCreditsError", "RateLimitError",
+]