ev-charging-status 0.1.6

Poll EV charging APIs and write station status events to TimescaleDB/PostgreSQL.

EV Charging Status

Python app that polls charger APIs and writes station status events to TimescaleDB/PostgreSQL.

Setup

The CLI is published on PyPI as ev-charging-status. Run it with uvx (no install/checkout needed):

uvx ev-charging-status --help

Provide DB credentials and API tokens via a .env file. The CLI loads, in order, the first file found in the current directory: config/.ev.env, .env, then config/.env. Copy the example and fill it in:

cp .env.example .env

.env is ignored by git. Run uvx commands from the directory that holds your env file so it gets picked up.

Developing from a source checkout instead? Run uv sync and use uv run ev-charging-status <command> in place of uvx ev-charging-status <command>.

Database

Initialize schema and seed default sites/statuses/stations:

uvx ev-charging-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:

uvx ev-charging-status init-db

Routine one-time poll:

uvx ev-charging-status poll

You can combine initialization and polling for a safe first run:

uvx ev-charging-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):

uvx ev-charging-status run-loop

For a safe first continuous run:

uvx ev-charging-status run-loop --init-db

Sync historical rows from the public Google Sheet CSV into station_status_events:

uvx ev-charging-status sync-sheet

Set SYNC_SHEET_ID in .env. By default the command reads Sheet1 using:

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:

uvx ev-charging-status sync-sheet --sheet-name Sheet1
uvx ev-charging-status sync-sheet --url 'https://docs.google.com/spreadsheets/d/{SHEETID}/gviz/tq?tqx=out:csv&sheet=Sheet1'

Optimize station_status_events storage:

uvx ev-charging-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:

uvx ev-charging-status optimize-db --compress-older-than '1 day'

Show total database size:

uvx ev-charging-status db-size
# include table/relation sizes
uvx ev-charging-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