aqi-in-api 0.0.2__py3-none-any.whl

aqi_in_api/__init__.py

@@ -0,0 +1,9 @@
+from aqi_in_api._client import AQIClient, ClientConfig, create_aqi_client
+from aqi_in_api._exceptions import AQIException
+
+__all__ = [
+    "AQIClient",
+    "AQIException",
+    "ClientConfig",
+    "create_aqi_client",
+]

aqi_in_api/_client.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import dataclasses
+import typing
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+import httpx
+
+from aqi_in_api._constants import DEFAULT_BASE_URL, DEFAULT_USER_AGENT, ENDPOINTS
+from aqi_in_api._exceptions import AQIException
+from aqi_in_api._token import generate_token
+from aqi_in_api._utils import build_url, get_slug_depth
+from aqi_in_api.models import (
+    HistoryData,
+    HistoryDataWithWHO,
+    IPDetails,
+    LocationDetails,
+    LocationType,
+    RankingEntry,
+    RankType,
+    SearchResults,
+    SearchType,
+    SensorName,
+    SlugType,
+    Station,
+)
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    token: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    user_agent: str = DEFAULT_USER_AGENT
+
+
+def _from_dict(model_cls: type[T], data: dict[str, Any]) -> T:
+    """Convert a nested dict into a frozen dataclass instance, skipping unknown fields."""
+    if not dataclasses.is_dataclass(model_cls) or not isinstance(data, dict):
+        return data  # type: ignore[return-value]
+    kwargs: dict[str, Any] = {}
+    for field in dataclasses.fields(model_cls):
+        if field.name not in data:
+            continue
+        kwargs[field.name] = _convert_value(field.type, data[field.name])
+    return model_cls(**kwargs)
+
+
+def _convert_value(field_type: object, value: Any) -> Any:
+    if value is None:
+        return None
+    origin = typing.get_origin(field_type)
+    args = typing.get_args(field_type)
+    if origin is typing.Union:
+        non_none = [a for a in args if a is not type(None)]
+        if non_none:
+            return _convert_value(non_none[0], value)
+        return None
+    if origin is list and args and isinstance(value, list):
+        return [_convert_value(args[0], item) for item in value]
+    if origin is tuple and args and isinstance(value, (list, tuple)):
+        return tuple(_convert_value(args[i], v) for i, v in enumerate(value[: len(args)]))
+    try:
+        if isinstance(value, dict) and dataclasses.is_dataclass(field_type):
+            return _from_dict(field_type, value)  # type: ignore[arg-type]
+    except TypeError:
+        pass
+    return value
+
+
+def _to_model(model_cls: type[T], data: Any) -> Any:
+    if isinstance(data, list):
+        return [_from_dict(model_cls, item) for item in data]
+    return _from_dict(model_cls, data)
+
+
+class AQIClient:
+    def __init__(self, config: ClientConfig | None = None) -> None:
+        config = config or ClientConfig()
+        self._base_url = config.base_url
+        self._custom_token = config.token
+        self._user_agent = config.user_agent
+        self._cached_token: str | None = None
+        self._http = httpx.AsyncClient()
+
+    async def _get_token(self) -> str:
+        if self._custom_token is not None:
+            return self._custom_token
+        if self._cached_token is None:
+            self._cached_token = generate_token()
+        return self._cached_token
+
+    async def _request(
+        self,
+        endpoint: str,
+        params: dict[str, str | int | float | None] | None = None,
+    ) -> Any:
+        url = build_url(self._base_url, endpoint, params)
+        token = await self._get_token()
+
+        response = await self._http.get(
+            url,
+            headers={
+                "User-Agent": self._user_agent,
+                "authorization": f"bearer {token}",
+            },
+        )
+
+        if not response.is_success:
+            raise AQIException(
+                f"Request failed: {response.status_code} {response.reason_phrase}",
+                response.status_code,
+                response.text,
+            )
+
+        body: dict[str, Any] = response.json()
+
+        if body.get("status") in ("failed",):
+            raise AQIException(
+                body.get("message") or body.get("error") or "Unknown error",
+                body.get("status_code", 400),
+            )
+
+        return body["data"]
+
+    async def get_ip_details(self) -> IPDetails:
+        data = await self._request(ENDPOINTS["IP_DETAILS"])
+        return _from_dict(IPDetails, data)
+
+    async def get_nearest_location(
+        self,
+        *,
+        lat: float,
+        long: float,
+        type: LocationType | None = None,
+    ) -> list[Station]:
+        data = await self._request(
+            ENDPOINTS["NEAREST_LOCATION"],
+            {"lat": lat, "long": long, "type": "2" if type == "city" else "1"},
+        )
+        return _to_model(Station, data)  # type: ignore[no-any-return]
+
+    async def get_location_by_slug(
+        self,
+        *,
+        slug: str,
+        type: SlugType | None = None,
+    ) -> list[LocationDetails]:
+        data = await self._request(
+            ENDPOINTS["LOCATION_BY_SLUG"],
+            {
+                "slug": slug,
+                "type": type if type is not None else get_slug_depth(slug),
+            },
+        )
+        return _to_model(LocationDetails, data)  # type: ignore[no-any-return]
+
+    async def search(self, *, search_string: str) -> SearchResults:
+        data = await self._request(ENDPOINTS["SEARCH"], {"searchString": search_string})
+        return _from_dict(SearchResults, data)
+
+    async def get_last_12_hour_history(
+        self,
+        *,
+        slug: str,
+        sensorname: SensorName,
+        slug_type: SearchType,
+    ) -> HistoryData:
+        data = await self._request(
+            ENDPOINTS["HISTORY_12H"],
+            {"slug": slug, "sensorname": sensorname, "slugType": slug_type},
+        )
+        return _from_dict(HistoryData, data)
+
+    async def get_last_24_hour_history(
+        self,
+        *,
+        slug: str,
+        sensorname: SensorName,
+        slug_type: SearchType,
+    ) -> HistoryDataWithWHO:
+        data = await self._request(
+            ENDPOINTS["HISTORY_24H"],
+            {"slug": slug, "sensorname": sensorname, "slugType": slug_type},
+        )
+        return _from_dict(HistoryDataWithWHO, data)
+
+    async def get_last_7_days_history(
+        self,
+        *,
+        slug: str,
+        sensorname: SensorName,
+        slug_type: SearchType,
+    ) -> HistoryDataWithWHO:
+        data = await self._request(
+            ENDPOINTS["HISTORY_7D"],
+            {"slug": slug, "sensorname": sensorname, "slugType": slug_type},
+        )
+        return _from_dict(HistoryDataWithWHO, data)
+
+    async def get_last_30_days_history(
+        self,
+        *,
+        slug: str,
+        sensorname: SensorName,
+        slug_type: SearchType,
+    ) -> HistoryDataWithWHO:
+        data = await self._request(
+            ENDPOINTS["HISTORY_30D"],
+            {"slug": slug, "sensorname": sensorname, "slugType": slug_type},
+        )
+        return _from_dict(HistoryDataWithWHO, data)
+
+    async def get_rankings(
+        self,
+        *,
+        sensorname: SensorName,
+        type: RankType,
+        limit: int = 10,
+    ) -> list[RankingEntry]:
+        data = await self._request(
+            ENDPOINTS["RANKINGS"],
+            {
+                "sensorname": sensorname,
+                "type": "1" if type == "country" else "2",
+                "limit": limit,
+            },
+        )
+        return _to_model(RankingEntry, data)  # type: ignore[no-any-return]
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+
+def create_aqi_client(config: ClientConfig | None = None) -> AQIClient:
+    return AQIClient(config)

aqi_in_api/_constants.py

@@ -0,0 +1,19 @@
+DEFAULT_BASE_URL = "https://apiserver.aqi.in"
+
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/143.0.0.0 Safari/537.36"
+)
+
+ENDPOINTS = {
+    "NEAREST_LOCATION": "/aqi/v2/getNearestLocation",
+    "IP_DETAILS": "/service/get/ip/details",
+    "LOCATION_BY_SLUG": "/aqi/v2/getLocationDetailsBySlug",
+    "SEARCH": "/aqi/searchLocationCityStateCountry",
+    "HISTORY_12H": "/aqi/getLast12HourHistory",
+    "HISTORY_24H": "/aqi/v3/getLast24HourHistory",
+    "HISTORY_7D": "/aqi/getLast7DaysHistory",
+    "HISTORY_30D": "/aqi/getLast30DaysHistory",
+    "RANKINGS": "/aqi/getAirQualityRanklistCountryAndCity",
+}

aqi_in_api/_exceptions.py

@@ -0,0 +1,12 @@
+class AQIException(Exception):
+    def __init__(self, message: str, status_code: int, body: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+        self.name = "AQIException"
+
+    def __str__(self) -> str:
+        if self.body:
+            return f"AQIException({self.status_code}): {self.message} - {self.body}"
+        return f"AQIException({self.status_code}): {self.message}"

aqi_in_api/_token.py

@@ -0,0 +1,17 @@
+import time
+
+import jwt
+
+JWT_SECRET = "masai"
+TOKEN_EXPIRY_SECONDS = 7 * 24 * 60 * 60
+
+
+def generate_token() -> str:
+    """Generate a JWT token matching the AQI.in API expectations."""
+    now = int(time.time())
+    payload = {
+        "userID": 1,
+        "iat": now,
+        "exp": now + TOKEN_EXPIRY_SECONDS,
+    }
+    return jwt.encode(payload, JWT_SECRET, algorithm="HS256")

aqi_in_api/_utils.py

@@ -0,0 +1,34 @@
+from collections.abc import Mapping
+from urllib.parse import urlencode, urljoin
+
+from aqi_in_api.models import SlugType
+
+
+def build_url(
+    base_url: str,
+    endpoint: str,
+    params: Mapping[str, str | int | float | None] | None = None,
+) -> str:
+    """Build a URL from base, endpoint, and query parameters.
+
+    Always appends ?source=web to match the TS SDK behavior.
+    """
+    url = urljoin(base_url.rstrip("/") + "/", endpoint.lstrip("/"))
+    query_params: dict[str, str] = {"source": "web"}
+
+    if params:
+        for key, value in params.items():
+            if value is not None:
+                query_params[key] = str(value)
+
+    return f"{url}?{urlencode(query_params)}"
+
+
+def get_slug_depth(slug: str) -> SlugType:
+    """Determine the slug depth (1=country, 2=state, 3=city, 4=station)."""
+    depth = slug.count("/") + 1
+    if depth < 1:
+        return 1
+    if depth > 4:
+        return 4
+    return depth  # type: ignore[return-value]

aqi_in_api/models.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+SensorName = Literal["pm25", "pm10", "aqi", "AQI-IN", "co", "no2", "o3", "so2"]
+SearchType = Literal["locationId", "cityId", "stateId", "countryId"]
+LocationType = Literal["station", "city"]
+SlugType = Literal[1, 2, 3, 4]
+RankType = Literal["city", "country"]
+
+
+@dataclass(frozen=True)
+class IAQI:
+    AQI_IN: int | None = None
+    aqi: int | None = None
+    pm25: int | None = None
+    pm10: int | None = None
+    co: int | None = None
+    no2: int | None = None
+    o3: int | None = None
+    so2: int | None = None
+    noise: int | None = None
+    tvoc: int | None = None
+    t: float | None = None
+
+
+@dataclass(frozen=True)
+class WeatherCondition:
+    text: str
+    icon: str
+    code: int
+
+
+@dataclass(frozen=True)
+class UVCondition:
+    text: str
+    color_code: str
+
+
+@dataclass(frozen=True)
+class Weather:
+    uid: str
+    cloud: int
+    condition: WeatherCondition
+    feelslike_c: float
+    feelslike_f: float
+    gust_kph: float
+    gust_mph: float
+    humidity: int
+    is_day: int
+    last_updated: str
+    last_updated_epoch: int
+    precip_in: float
+    precip_mm: float
+    pressure_in: float
+    pressure_mb: float
+    temp_c: float
+    temp_f: float
+    uv: float
+    vis_km: float
+    vis_miles: float
+    wind_degree: int
+    wind_dir: str
+    wind_kph: float
+    wind_mph: float
+    uv_condition: UVCondition | None = None
+
+
+@dataclass(frozen=True)
+class WeatherSimple:
+    temp_c: float
+    temp_f: float
+
+
+@dataclass(frozen=True, kw_only=True)
+class BaseLocation:
+    location: str
+    locationId: str
+    slug: str
+    latitude: float
+    longitude: float
+    flag: str
+    searchType: SearchType
+    uid: str | None = None
+
+
+@dataclass(frozen=True)
+class Station(BaseLocation):
+    station: str
+    city: str
+    state: str
+    country: str
+    location_slug: str
+    city_slug: str
+    state_slug: str
+    country_slug: str
+    time_zone: str
+    coordinates: tuple[float, float]
+    background_image: str
+    city_lat: float
+    city_lon: float
+    state_lat: float
+    state_lon: float
+    country_lat: float
+    country_lon: float
+    isOnline: bool
+    isRankedCity: bool
+    iaqi: IAQI
+    updated_at: str
+    weather: Weather | None = None
+    updatedAt: str | None = None
+    createdAt: str | None = None
+    distance: float | None = None
+    source: str | None = None
+
+
+@dataclass(frozen=True)
+class City(BaseLocation):
+    city: str
+    state: str
+    country: str
+    weather: WeatherSimple | None = None
+    iaqi: IAQI | None = None
+
+
+@dataclass(frozen=True)
+class State(BaseLocation):
+    state: str
+    country: str
+
+
+@dataclass(frozen=True)
+class Country(BaseLocation):
+    pass
+
+
+@dataclass(frozen=True)
+class IPDetails:
+    city: str
+    country: str
+    countryCode: str
+    lat: float
+    lon: float
+    offset: int
+    query: str
+    regionName: str
+    status: str
+    timezone: str
+    zip: str
+
+
+@dataclass(frozen=True)
+class LocationDetails:
+    uid: str
+    location: str
+    country: str
+    time_zone: str
+    latitude: float
+    longitude: float
+    country_slug: str
+    background_image: str
+    flag: str
+    country_lat: float
+    country_lon: float
+    isOnline: bool
+    isRankedCity: bool
+    iaqi: IAQI
+    updated_at: str
+    locationId: str
+    searchType: SearchType
+    slug: str
+    station: str | None = None
+    city: str | None = None
+    state: str | None = None
+    location_slug: str | None = None
+    city_slug: str | None = None
+    state_slug: str | None = None
+    city_lat: float | None = None
+    city_lon: float | None = None
+    state_lat: float | None = None
+    state_lon: float | None = None
+    weather: Weather | None = None
+    updatedAt: str | None = None
+
+
+@dataclass(frozen=True)
+class HistoryData:
+    minValue: float
+    maxValue: float
+    avgValue: float
+    averageArray: list[float]
+    timeArray: list[str]
+
+
+@dataclass(frozen=True)
+class WHOGuideData:
+    Data: HistoryData
+
+
+@dataclass(frozen=True)
+class HistoryDataWithWHO(HistoryData):
+    whoguidedata: WHOGuideData | None = None
+
+
+@dataclass(frozen=True)
+class SearchResults:
+    countries: list[Country]
+    states: list[State]
+    cities: list[City]
+    stations: list[Station]
+
+
+@dataclass(frozen=True)
+class RankingEntry:
+    location: str
+    locationId: str
+    flag: str
+    slug: str
+    latitude: float
+    longitude: float
+    updated_at: str
+    rank: int
+    city: str | None = None
+    state: str | None = None
+    country: str | None = None
+    pm25: float | None = None
+    pm10: float | None = None
+    aqi: float | None = None

aqi_in_api-0.0.2.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: aqi-in-api
+Version: 0.0.2
+Summary: Python SDK for the AQI.in Air Quality API
+Project-URL: Repository, https://github.com/GuyKh/py-aqi-in-api
+Project-URL: Issues, https://github.com/GuyKh/py-aqi-in-api/issues
+Author: GuyKh
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pyjwt>=2.10.0
+Description-Content-Type: text/markdown
+
+# py-aqi-in-api
+
+Python SDK for the [AQI.in](https://aqi.in) Air Quality API.
+
+Fully typed, async, using modern Python (3.11+), dataclasses, and httpx.
+
+> **Source**: This is a Python port of the [aqi-in-api](https://github.com/neo773/aqi-in-api) TypeScript SDK by [@neo773](https://github.com/neo773).
+
+## Installation
+
+```bash
+pip install py-aqi-in-api
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+```python
+import asyncio
+
+from aqi_in_api import AQIClient
+
+
+async def main() -> None:
+    client = AQIClient()
+
+    ip_details = await client.get_ip_details()
+    print(f"Location: {ip_details.city}, {ip_details.country}")
+
+    nearest = await client.get_nearest_location(
+        lat=ip_details.lat, long=ip_details.lon,
+    )
+    station = nearest[0]
+    print(f"Nearest station: {station.station} ({station.location_slug})")
+
+    location = await client.get_location_by_slug(slug=station.location_slug)
+    print(f"Location AQI: {location[0].iaqi}")
+
+    history = await client.get_last_24_hour_history(
+        slug=station.location_slug, sensorname="pm25", slug_type="locationId",
+    )
+    print(f"24h PM2.5 avg: {history.avgValue}")
+
+    await client.close()
+
+
+asyncio.run(main())
+```
+
+## API
+
+### `create_aqi_client(config?)`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `token` | `str \| None` | No | JWT authentication token (auto-generated if omitted) |
+| `base_url` | `str` | No | API base URL (default: `https://apiserver.aqi.in`) |
+| `user_agent` | `str` | No | Custom user agent |
+
+### Methods
+
+All methods take keyword-only arguments. No `*Params` objects needed.
+
+| Method | Keyword Args | Returns | Description |
+|--------|-------------|---------|-------------|
+| `get_ip_details()` | — | `IPDetails` | Get location from your IP address |
+| `get_nearest_location(**kwargs)` | `lat`, `long`, `type?` | `list[Station]` | Get nearest monitoring stations by coordinates |
+| `get_location_by_slug(**kwargs)` | `slug`, `type?` | `list[LocationDetails]` | Get location details by slug |
+| `search(**kwargs)` | `search_string` | `SearchResults` | Search locations by name |
+| `get_last_12_hour_history(**kwargs)` | `slug`, `sensorname`, `slug_type` | `HistoryData` | Get 12-hour sensor history |
+| `get_last_24_hour_history(**kwargs)` | `slug`, `sensorname`, `slug_type` | `HistoryDataWithWHO` | Get 24-hour history with WHO guidelines |
+| `get_last_7_days_history(**kwargs)` | `slug`, `sensorname`, `slug_type` | `HistoryDataWithWHO` | Get 7-day sensor history |
+| `get_last_30_days_history(**kwargs)` | `slug`, `sensorname`, `slug_type` | `HistoryDataWithWHO` | Get 30-day sensor history |
+| `get_rankings(**kwargs)` | `sensorname`, `type`, `limit=10` | `list[RankingEntry]` | Get city or country pollution rankings |
+| `close()` | — | `None` | Close the underlying HTTP client |
+
+### Types
+
+```python
+from aqi_in_api.models import (
+    Station, City, State, Country,
+    LocationDetails, IPDetails, SearchResults, RankingEntry,
+    HistoryData, HistoryDataWithWHO,
+    IAQI, Weather, WeatherCondition, WeatherSimple, UVCondition,
+    SensorName, SearchType, SlugType, LocationType, RankType,
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/GuyKh/py-aqi-in-api
+cd py-aqi-in-api
+uv sync --dev
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT
+
+## Disclaimer
+
+This is an **unofficial** API client and is not affiliated with, endorsed by, or associated with AQI.in or its parent organization. This package is provided for educational and informational purposes under fair use.

aqi_in_api-0.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+aqi_in_api/__init__.py,sha256=tOi5xmSkkC73UJ0O_SWO5yCPxr-jm8XIsIN7CXcP5Fg,219
+aqi_in_api/_client.py,sha256=JAlDVsFHx8SO47Nb95tpc2ULcc0UNZHDhuyW7hsMqac,7358
+aqi_in_api/_constants.py,sha256=HQQPFkx2YCZLvkLyh-6ETM0dvcUIwOxYxficu8jKFH4,692
+aqi_in_api/_exceptions.py,sha256=er7r1oTU_deiN41HsEsJJVKOn_vuoM_eI0QMcYZ92Lw,489
+aqi_in_api/_token.py,sha256=bW4W1T2zJ81VP2Sa2wK39xVpqNgXMdvgYn_w7S1T8Ao,381
+aqi_in_api/_utils.py,sha256=YZU3LHL46hl5MuQf00jrHtmS4_g1O8AFLRufoqGiFy8,960
+aqi_in_api/models.py,sha256=OrhVBX1QTWT_tWk2m-6q18EATaAiYNwJY_HlSBjNhDk,4593
+aqi_in_api-0.0.2.dist-info/METADATA,sha256=Su3lS1yPGCxxhXOPTsdhjaDt0nRmoLSrXNXLkFCFQPk,3944
+aqi_in_api-0.0.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+aqi_in_api-0.0.2.dist-info/RECORD,,

aqi_in_api-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any