ev-charging-status 0.1.0__tar.gz

ev_charging_status-0.1.0/LICENSE

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

ev_charging_status-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: ev-charging-status
+Version: 0.1.0
+Summary: Poll EV charging APIs and write station status events to TimescaleDB/PostgreSQL.
+Author: guocity
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/guocity/ev_charging_status
+Project-URL: Repository, https://github.com/guocity/ev_charging_status
+Keywords: ev,charging,timescaledb,postgresql,polling
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg[binary]<4,>=3.1
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: requests<3,>=2.31
+Dynamic: license-file
+
+# EV Charging Status
+
+Python app that polls Shell Recharge/Greenlots and SEMA/Blink charger APIs and writes station status events to TimescaleDB/PostgreSQL.
+
+## Setup
+
+```bash
+uv sync
+cp .env.example .env
+```
+
+Put real DB credentials and API tokens in `.env`. `.env` is ignored by git.
+
+Run commands through `uv run`, for example:
+
+```bash
+uv run ev-status --help
+```
+
+## Database
+
+Initialize schema and seed default sites/statuses/stations:
+
+```bash
+uv run ev-status init-db
+```
+
+Only rows with `sites.enabled = true` are polled.
+
+## Run
+
+First run, or after recreating/changing the database schema, initialize the database once:
+
+```bash
+uv run ev-status init-db
+```
+
+Routine one-time poll:
+
+```bash
+uv run ev-status poll
+```
+
+You can combine initialization and polling for a safe first run:
+
+```bash
+uv run ev-status poll --init-db
+```
+
+`--init-db` is not required for every poll. It only ensures the database, tables, indexes, default sites, default statuses, default stations, and TimescaleDB setup exist before polling.
+
+Continuous 5-minute loop (or `POLL_INTERVAL_SECONDS`):
+
+```bash
+uv run ev-status run-loop
+```
+
+For a safe first continuous run:
+
+```bash
+uv run ev-status run-loop --init-db
+```
+
+Sync historical rows from the public Google Sheet CSV into `station_status_events`:
+
+```bash
+uv run ev-status sync-sheet
+```
+
+Set `SYNC_SHEET_ID` in `.env`. By default the command reads `Sheet1` using:
+
+```text
+https://docs.google.com/spreadsheets/d/<SYNC_SHEET_ID>/gviz/tq?tqx=out:csv&sheet=Sheet1
+```
+
+The sheet must include columns like `current_time`, `station_name`, and `status`. The sync command inserts only rows that do not already exist with the same `(time, station_id, status)`. Rows for station IDs not present in the `stations` table are ignored.
+
+You can override the tab or full CSV URL:
+
+```bash
+uv run ev-status sync-sheet --sheet-name Sheet1
+uv run ev-status sync-sheet --url 'https://docs.google.com/spreadsheets/d/{SHEETID}/gviz/tq?tqx=out:csv&sheet=Sheet1'
+```
+
+Optimize `station_status_events` storage:
+
+```bash
+uv run ev-status optimize-db
+```
+
+This rounds existing event timestamps to second precision, drops the redundant `(time DESC, station_id)` index, and compresses TimescaleDB chunks older than 7 days. Timestamp precision is also second-level for new polls.
+
+You can change the compression cutoff:
+
+```bash
+uv run ev-status optimize-db --compress-older-than '1 day'
+```
+
+Show total database size:
+
+```bash
+uv run ev-status db-size
+# include table/relation sizes
+uv run ev-status db-size --tables
+```
+
+## Tables
+
+- `sites`: site enable/disable control
+- `status_lookup`: status IDs; new normalized statuses are inserted automatically
+- `stations`: station metadata inserted once on first sight
+- `station_status_events`: Timescale hypertable with exactly `(time, station_id, status)`
+- `site_latest_snapshot`: latest raw JSONB API response per site

ev_charging_status-0.1.0/README.md

@@ -0,0 +1,113 @@
+# EV Charging Status
+
+Python app that polls Shell Recharge/Greenlots and SEMA/Blink charger APIs and writes station status events to TimescaleDB/PostgreSQL.
+
+## Setup
+
+```bash
+uv sync
+cp .env.example .env
+```
+
+Put real DB credentials and API tokens in `.env`. `.env` is ignored by git.
+
+Run commands through `uv run`, for example:
+
+```bash
+uv run ev-status --help
+```
+
+## Database
+
+Initialize schema and seed default sites/statuses/stations:
+
+```bash
+uv run ev-status init-db
+```
+
+Only rows with `sites.enabled = true` are polled.
+
+## Run
+
+First run, or after recreating/changing the database schema, initialize the database once:
+
+```bash
+uv run ev-status init-db
+```
+
+Routine one-time poll:
+
+```bash
+uv run ev-status poll
+```
+
+You can combine initialization and polling for a safe first run:
+
+```bash
+uv run ev-status poll --init-db
+```
+
+`--init-db` is not required for every poll. It only ensures the database, tables, indexes, default sites, default statuses, default stations, and TimescaleDB setup exist before polling.
+
+Continuous 5-minute loop (or `POLL_INTERVAL_SECONDS`):
+
+```bash
+uv run ev-status run-loop
+```
+
+For a safe first continuous run:
+
+```bash
+uv run ev-status run-loop --init-db
+```
+
+Sync historical rows from the public Google Sheet CSV into `station_status_events`:
+
+```bash
+uv run ev-status sync-sheet
+```
+
+Set `SYNC_SHEET_ID` in `.env`. By default the command reads `Sheet1` using:
+
+```text
+https://docs.google.com/spreadsheets/d/<SYNC_SHEET_ID>/gviz/tq?tqx=out:csv&sheet=Sheet1
+```
+
+The sheet must include columns like `current_time`, `station_name`, and `status`. The sync command inserts only rows that do not already exist with the same `(time, station_id, status)`. Rows for station IDs not present in the `stations` table are ignored.
+
+You can override the tab or full CSV URL:
+
+```bash
+uv run ev-status sync-sheet --sheet-name Sheet1
+uv run ev-status sync-sheet --url 'https://docs.google.com/spreadsheets/d/{SHEETID}/gviz/tq?tqx=out:csv&sheet=Sheet1'
+```
+
+Optimize `station_status_events` storage:
+
+```bash
+uv run ev-status optimize-db
+```
+
+This rounds existing event timestamps to second precision, drops the redundant `(time DESC, station_id)` index, and compresses TimescaleDB chunks older than 7 days. Timestamp precision is also second-level for new polls.
+
+You can change the compression cutoff:
+
+```bash
+uv run ev-status optimize-db --compress-older-than '1 day'
+```
+
+Show total database size:
+
+```bash
+uv run ev-status db-size
+# include table/relation sizes
+uv run ev-status db-size --tables
+```
+
+## Tables
+
+- `sites`: site enable/disable control
+- `status_lookup`: status IDs; new normalized statuses are inserted automatically
+- `stations`: station metadata inserted once on first sight
+- `station_status_events`: Timescale hypertable with exactly `(time, station_id, status)`
+- `site_latest_snapshot`: latest raw JSONB API response per site

ev_charging_status-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ev-charging-status"
+version = "0.1.0"
+description = "Poll EV charging APIs and write station status events to TimescaleDB/PostgreSQL."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "guocity" }]
+keywords = ["ev", "charging", "timescaledb", "postgresql", "polling"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "psycopg[binary]>=3.1,<4",
+  "python-dotenv>=1.0,<2",
+  "requests>=2.31,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/guocity/ev_charging_status"
+Repository = "https://github.com/guocity/ev_charging_status"
+
+[project.scripts]
+ev-status = "ev_charging_status.cli:main"
+ev-charging-status = "ev_charging_status.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ev_charging_status-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ev_charging_status-0.1.0/src/ev_charging_status/__init__.py

@@ -0,0 +1,3 @@
+"""EV charging status polling package."""
+
+__version__ = "0.1.0"

ev_charging_status-0.1.0/src/ev_charging_status/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ev_charging_status-0.1.0/src/ev_charging_status/api/__init__.py

@@ -0,0 +1,9 @@
+from .client import ChargingApiClient
+from .sema import SemaLocationEndpoint
+from .shellrecharge import ShellRechargeSiteSearchEndpoint
+
+__all__ = [
+    "ChargingApiClient",
+    "SemaLocationEndpoint",
+    "ShellRechargeSiteSearchEndpoint",
+]

ev_charging_status-0.1.0/src/ev_charging_status/api/base.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import logging
+import time
+from collections import deque
+from typing import Any, Optional
+
+import requests
+
+from ..config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+class BaseApiEndpoint:
+    """Shared HTTP, retry, and rate-limit helpers for API endpoint clients."""
+
+    def __init__(self, settings: Settings, session: Optional[requests.Session] = None) -> None:
+        self.settings = settings
+        self.session = session or requests.Session()
+        self._calls: deque[float] = deque()
+
+    def _wait_for_rate_limit(self, *, max_calls: int, period_seconds: int) -> None:
+        now = time.monotonic()
+        while self._calls and now - self._calls[0] >= period_seconds:
+            self._calls.popleft()
+        if len(self._calls) >= max_calls:
+            sleep_for = period_seconds - (now - self._calls[0])
+            if sleep_for > 0:
+                logger.info("API rate limit reached; sleeping %.2f seconds", sleep_for)
+                time.sleep(sleep_for)
+            now = time.monotonic()
+            while self._calls and now - self._calls[0] >= period_seconds:
+                self._calls.popleft()
+        self._calls.append(time.monotonic())
+
+    def _get_json(self, url: str, headers: Optional[dict[str, str]] = None) -> Optional[Any]:
+        for attempt in range(1, 4):
+            try:
+                response = self.session.get(url, headers=headers, timeout=self.settings.request_timeout)
+                response.raise_for_status()
+                return response.json()
+            except (requests.RequestException, ValueError) as exc:
+                if attempt < 3:
+                    sleep_for = 2 ** (attempt - 1)
+                    logger.warning("HTTP/JSON error for %s (attempt %s/3): %s", url, attempt, exc)
+                    time.sleep(sleep_for)
+                else:
+                    logger.warning("HTTP/JSON error for %s: %s", url, exc)
+        return None

ev_charging_status-0.1.0/src/ev_charging_status/api/client.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+from ..config import Settings
+from .sema import SemaLocationEndpoint
+from .shellrecharge import ShellRechargeSiteSearchEndpoint
+
+
+class ChargingApiClient:
+    """Convenience facade over individual endpoint clients."""
+
+    def __init__(self, settings: Settings, session: Optional[requests.Session] = None) -> None:
+        self.settings = settings
+        self.session = session or requests.Session()
+        self.shellrecharge_site_search = ShellRechargeSiteSearchEndpoint(settings, session=self.session)
+        self.sema_location = SemaLocationEndpoint(settings, session=self.session)
+
+    def fetch_shellrecharge_by_siteid(self, site_id: str) -> Optional[Any]:
+        return self.shellrecharge_site_search.fetch(site_id)
+
+    def fetch_sema_station_json(self) -> Optional[Any]:
+        return self.sema_location.fetch()

ev_charging_status-0.1.0/src/ev_charging_status/api/sema.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+from ..config import Settings
+from .base import BaseApiEndpoint
+
+
+class SemaLocationEndpoint(BaseApiEndpoint):
+    """SEMA/Blink location endpoint containing charger statuses."""
+
+    rate_limit_calls = 2
+    rate_limit_period_seconds = 10
+
+    def __init__(self, settings: Settings, session: Optional[requests.Session] = None) -> None:
+        super().__init__(settings, session=session)
+
+    def fetch(self) -> Optional[Any]:
+        self._wait_for_rate_limit(
+            max_calls=self.rate_limit_calls,
+            period_seconds=self.rate_limit_period_seconds,
+        )
+        url = self.settings.sema_api_url or (
+            "https://apigw.blinknetwork.com/v1/locations/"
+            f"{self.settings.sema_location_id}?isPrivateStationReq=false"
+        )
+        headers = {
+            "accept": "application/json",
+            "x-ios-bundle-identifier": "com.blinknetwork.mobile2",
+            "priority": "u=3, i",
+            "accept-language": "en-US,en;q=0.9",
+            "os-type": "ios",
+            "device-os-version": "19.0",
+            "user-agent": "BlinkMobile/1034 CFNetwork Darwin",
+            "x-app-version": "3.1.25",
+            "device-locale": "en-US",
+        }
+        if self.settings.sema_authorization:
+            auth = self.settings.sema_authorization.strip()
+            headers["authorization"] = auth if auth.lower().startswith("bearer ") else f"Bearer {auth}"
+        if self.settings.sema_firebase_appcheck:
+            headers["x-firebase-appcheck"] = self.settings.sema_firebase_appcheck
+        return self._get_json(url, headers=headers)

ev_charging_status-0.1.0/src/ev_charging_status/api/shellrecharge.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+from ..config import Settings
+from .base import BaseApiEndpoint
+
+
+class ShellRechargeSiteSearchEndpoint(BaseApiEndpoint):
+    """Shell Recharge / Greenlots site search endpoint."""
+
+    rate_limit_calls = 4
+    rate_limit_period_seconds = 10
+
+    def __init__(self, settings: Settings, session: Optional[requests.Session] = None) -> None:
+        super().__init__(settings, session=session)
+
+    def fetch(self, site_id: str) -> Optional[Any]:
+        self._wait_for_rate_limit(
+            max_calls=self.rate_limit_calls,
+            period_seconds=self.rate_limit_period_seconds,
+        )
+        url = f"https://sky.shellrecharge.com/greenlots/coreapi/v4/sites/search/{site_id}"
+        headers = {
+            "accept": "*/*",
+            "content-type": "application/json",
+            "accept-language": "en",
+            "user-agent": "Shell Recharge/7.6.0 (com.zecosystems.greenlots; build:412; iOS) Alamofire/5.9.1",
+            "priority": "u=3, i",
+        }
+        if self.settings.shell_cookie:
+            headers["Cookie"] = self.settings.shell_cookie
+        elif self.settings.shell_jsessionid:
+            headers["Cookie"] = f'JSESSIONID="{self.settings.shell_jsessionid}"'
+        return self._get_json(url, headers=headers)

ev_charging_status-0.1.0/src/ev_charging_status/cli.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from .config import Settings
+from .service import ChargingStatusService
+
+
+def _configure_logging(verbose: bool = False) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Poll EV charging status into TimescaleDB/PostgreSQL.")
+    parser.add_argument("--verbose", action="store_true", help="Enable debug logging")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("init-db", help="Create schema and seed sites/statuses/stations")
+
+    poll_parser = subparsers.add_parser("poll", help="Run one polling cycle")
+    poll_parser.add_argument("--init-db", action="store_true", help="Initialize schema before polling")
+
+    loop_parser = subparsers.add_parser("run-loop", help="Poll forever every POLL_INTERVAL_SECONDS")
+    loop_parser.add_argument("--init-db", action="store_true", help="Initialize schema before starting loop")
+
+    sync_parser = subparsers.add_parser(
+        "sync-sheet",
+        help="Sync historical station_status_events from a public Google Sheet CSV",
+    )
+    sync_parser.add_argument("--init-db", action="store_true", help="Initialize schema before syncing")
+    sync_parser.add_argument("--sheet-name", help="Google Sheet tab name; defaults to SYNC_SHEET_NAME or Sheet1")
+    sync_parser.add_argument("--url", help="Override CSV URL; otherwise built from SYNC_SHEET_ID")
+
+    optimize_parser = subparsers.add_parser(
+        "optimize-db",
+        help="Optimize station_status_events storage",
+    )
+    optimize_parser.add_argument(
+        "--compress-older-than",
+        default="7 days",
+        help="Compress chunks older than this PostgreSQL interval; default: 7 days",
+    )
+    optimize_parser.add_argument(
+        "--keep-redundant-index",
+        action="store_true",
+        help="Keep idx_sse_site_time instead of dropping it",
+    )
+
+    size_parser = subparsers.add_parser("db-size", help="Show PostgreSQL database size")
+    size_parser.add_argument("--tables", action="store_true", help="Also show table/relation sizes")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    _configure_logging(args.verbose)
+
+    settings = Settings.from_env()
+    service = ChargingStatusService(settings)
+
+    if args.command == "init-db":
+        service.init_db()
+        return 0
+    if args.command == "poll":
+        inserted = service.poll_once(init_schema=args.init_db)
+        logging.getLogger(__name__).info("Inserted %s total status events", inserted)
+        return 0
+    if args.command == "run-loop":
+        service.run_forever(init_schema=args.init_db)
+        return 0
+    if args.command == "sync-sheet":
+        stats = service.sync_google_sheet(
+            init_schema=args.init_db,
+            sheet_name=args.sheet_name,
+            csv_url=args.url,
+        )
+        print(
+            "Synced Google Sheet: "
+            f"fetched_rows={stats['fetched_rows']}, "
+            f"parsed_rows={stats['parsed_rows']}, "
+            f"skipped_parse_rows={stats['skipped_parse_rows']}, "
+            f"unique_rows={stats['unique_rows']}, "
+            f"skipped_unknown_stations={stats['skipped_unknown_stations']}, "
+            f"inserted_rows={stats['inserted_rows']}"
+        )
+        return 0
+    if args.command == "optimize-db":
+        stats = service.optimize_database(
+            compress_older_than=args.compress_older_than,
+            drop_redundant_index=not args.keep_redundant_index,
+        )
+        print(
+            "Optimized database: "
+            f"rounded_time_rows={stats['rounded_time_rows']}, "
+            f"dropped_redundant_index={stats['dropped_redundant_index']}, "
+            f"compressed_chunks={stats['compressed_chunks']}"
+        )
+        return 0
+    if args.command == "db-size":
+        size = service.get_database_size()
+        print(f"{size['database_name']}: {size['size_pretty']} ({size['size_bytes']} bytes)")
+        if args.tables:
+            for row in service.get_relation_sizes():
+                print(f"{row['relation_name']}: {row['size_pretty']} ({row['size_bytes']} bytes)")
+        return 0
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())