aqi-in-api 0.0.2__tar.gz

aqi_in_api-0.0.2/.github/CODEOWNERS

@@ -0,0 +1 @@
+@GuyKh

aqi_in_api-0.0.2/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: guykh # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: guykh # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

aqi_in_api-0.0.2/.github/ISSUE_TEMPLATE/1-question.md

@@ -0,0 +1,11 @@
+---
+name: Question
+about: Questions about this project
+labels: question
+---
+
+### Checklist
+- [ ] There are no similar issues or pull requests about this question.
+
+### Describe your question
+<!-- A clear and concise description of what the question is. -->

aqi_in_api-0.0.2/.github/ISSUE_TEMPLATE/2-bug-report.md

@@ -0,0 +1,19 @@
+---
+name: Bug report
+about: Report a bug to help improve this project
+labels: bug
+---
+### Describe the bug
+<!-- A clear and concise description of what the bug is. -->
+
+### To reproduce
+<!-- Provide a *minimal* example with steps to reproduce the bug locally.-->
+
+### Expected behavior
+<!-- A clear and concise description of what you expected to happen. -->
+
+### Actual behavior
+<!-- A clear and concise description of what actually happens. -->
+
+
+### Additional context

aqi_in_api-0.0.2/.github/ISSUE_TEMPLATE/3-feature-request.md

@@ -0,0 +1,33 @@
+---
+name: Feature request
+about: Suggest an idea for this project.
+labels: feature, enhancement
+---
+
+### Checklist
+
+<!-- Please make sure you check all these items before submitting your feature request. -->
+
+- [ ] There are no similar issues or pull requests for this yet.
+
+### Is your feature related to a problem? Please describe.
+
+<!-- A clear and concise description of what you are trying to achieve.
+
+Eg "I want to be able to [...] but I can't because [...]". -->
+
+## Describe the solution you would like.
+
+<!-- A clear and concise description of what you would want to happen.
+
+For API changes, try to provide a code snippet of what you would like the API to look like.
+-->
+
+## Describe alternatives you considered
+
+<!-- Please describe any alternative solutions or features you've considered to solve
+your problem and why they wouldn't solve it. -->
+
+## Additional context
+
+<!-- Provide any additional context, screenshots, tracebacks, etc. about the feature here. -->

aqi_in_api-0.0.2/.github/PULL_REQUEST_TEMPLATE

@@ -0,0 +1,5 @@
+## What changes do you are proposing?
+
+## How did you test these changes? 
+
+**Closing issues**

aqi_in_api-0.0.2/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

aqi_in_api-0.0.2/.github/workflows/publish.yml

@@ -0,0 +1,97 @@
+name: release
+
+on:
+    push:
+        tags:
+            - "[0-9]+.[0-9]+.[0-9]+"
+            - "[0-9]+.[0-9]+.[0-9]+a[0-9]+"
+            - "[0-9]+.[0-9]+.[0-9]+b[0-9]+"
+            - "[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+
+env:
+    PACKAGE_NAME: "py-aqi-in-api"
+    OWNER: "GuyKh"
+
+jobs:
+    details:
+        runs-on: ubuntu-latest
+        outputs:
+            new_version: ${{ steps.release.outputs.new_version }}
+            suffix: ${{ steps.release.outputs.suffix }}
+            tag_name: ${{ steps.release.outputs.tag_name }}
+        steps:
+            - uses: actions/checkout@v7
+
+            - name: Extract tag and Details
+              id: release
+              run: |
+                  if [ "${{ github.ref_type }}" = "tag" ]; then
+                    TAG_NAME=${GITHUB_REF#refs/tags/}
+                    NEW_VERSION=$(echo $TAG_NAME | awk -F'-' '{print $1}')
+                    SUFFIX=$(echo $TAG_NAME | grep -oP '[a-z]+[0-9]+' || echo "")
+                    echo "new_version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+                    echo "suffix=$SUFFIX" >> "$GITHUB_OUTPUT"
+                    echo "tag_name=$TAG_NAME" >> "$GITHUB_OUTPUT"
+                    echo "Version is $NEW_VERSION"
+                    echo "Suffix is $SUFFIX"
+                    echo "Tag name is $TAG_NAME"
+                  else
+                    echo "No tag found"
+                    exit 1
+                  fi
+
+    check_pypi:
+        needs: details
+        runs-on: ubuntu-latest
+        steps:
+            - name: Fetch information from PyPI
+              run: |
+                  response=$(curl -s https://pypi.org/pypi/${{ env.PACKAGE_NAME }}/json || echo "{}")
+                  latest_previous_version=$(echo $response | jq --raw-output "select(.releases != null) | .releases | keys_unsorted | last")
+                  if [ -z "$latest_previous_version" ]; then
+                    echo "Package not found on PyPI."
+                    latest_previous_version="0.0.0"
+                  fi
+                  echo "Latest version on PyPI: $latest_previous_version"
+                  echo "latest_previous_version=$latest_previous_version" >> $GITHUB_ENV
+
+            - name: Compare versions and exit if not newer
+              run: |
+                  NEW_VERSION=${{ needs.details.outputs.new_version }}
+                  LATEST_VERSION=$latest_previous_version
+                  if [ "$(printf '%s\n' "$LATEST_VERSION" "$NEW_VERSION" | sort -rV | head -n 1)" != "$NEW_VERSION" ] || [ "$NEW_VERSION" == "$LATEST_VERSION" ]; then
+                    echo "The new version $NEW_VERSION is not greater than the latest version $LATEST_VERSION on PyPI."
+                    exit 1
+                  else
+                    echo "The new version $NEW_VERSION is greater than the latest version $LATEST_VERSION on PyPI."
+                  fi
+
+    setup_and_build:
+        needs: [details, check_pypi]
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v7
+
+            - name: Set up Python
+              uses: actions/setup-python@v6
+              with:
+                  python-version: "3.11"
+
+            - name: Install uv
+              uses: astral-sh/setup-uv@v8.2.0
+              with:
+                  enable-cache: true
+
+            - name: Set project version
+              run: |
+                  uv version ${{ needs.details.outputs.new_version }}
+
+            - name: Install dependencies
+              run: uv sync
+
+            - name: Build source publish
+              env:
+                  PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+              run: |
+                  uv build
+                  uv publish --token $PYPI_TOKEN

aqi_in_api-0.0.2/.github/workflows/pull_request.yml

@@ -0,0 +1,66 @@
+name: pull_request
+on: [pull_request]
+jobs:
+  lint:
+    name: "Lint"
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Running lint for ${{ github.ref }} branch"
+
+      - name: Check out repository code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Running Lint
+        run: uv run --with ruff ruff check .
+
+  run_tests:
+    name: "Run Tests"
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Running tests for ${{ github.ref }} branch"
+
+      - name: Check out repository code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Running tests
+        run: uv run --with pytest --with pytest-cov pytest --cov-report=term --cov .
+
+  mypy:
+    name: "Mypy Validation"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Running Mypy
+        run: uv run --with mypy python3 -m mypy src/ tests/ --follow-untyped-imports --explicit-package-bases --check-untyped-defs

aqi_in_api-0.0.2/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environment
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Coverage
+.coverage
+htmlcov/
+coverage/
+
+# Environment
+.env
+
+# Local tooling
+token-optimizer/

aqi_in_api-0.0.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,106 @@
+# 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/example.py

@@ -0,0 +1,38 @@
+import asyncio
+
+from aqi_in_api import create_aqi_client
+
+
+async def main() -> None:
+    client = create_aqi_client()
+
+    ip_details = await client.get_ip_details()
+    print(ip_details)
+
+    nearest_location = await client.get_nearest_location(
+        lat=ip_details.lat,
+        long=ip_details.lon,
+    )
+    print(nearest_location)
+
+    station = nearest_location[0].location_slug
+
+    location_details = await client.get_location_by_slug(slug=station)
+    print(location_details)
+
+    history = await client.get_last_24_hour_history(
+        slug=station,
+        sensorname="pm25",
+        slug_type="locationId",
+    )
+    print(history)
+
+    history_30_days = await client.get_last_30_days_history(
+        slug=station,
+        sensorname="pm25",
+        slug_type="locationId",
+    )
+    print(history_30_days)
+
+
+asyncio.run(main())

aqi_in_api-0.0.2/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "aqi-in-api"
+version = "0.0.2"
+description = "Python SDK for the AQI.in Air Quality API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "GuyKh" },
+]
+
+dependencies = [
+    "httpx>=0.28.0",
+    "pyjwt>=2.10.0",
+]
+
+[project.urls]
+Repository = "https://github.com/GuyKh/py-aqi-in-api"
+Issues = "https://github.com/GuyKh/py-aqi-in-api/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aqi_in_api"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/aqi_in_api/models.py" = ["N815"]
+"src/aqi_in_api/_exceptions.py" = ["N818"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src/"]
+follow_untyped_imports = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "pytest_httpx"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-httpx>=0.36.2",
+    "ruff>=0.15.20",
+]

aqi_in_api-0.0.2/src/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",
+]