pychargefox

Async Python client for the Chargefox GraphQL API.

[!WARNING] This is an unofficial project and is not affiliated with, endorsed by, or connected to Chargefox. It uses an undocumented GraphQL API that may change or stop working without notice.

[!NOTE] This project was developed with AI-assisted coding. Its behavior has been reviewed and tested, but users should independently evaluate it before relying on it.

Install

pip install pychargefox

For local development, install the project into its virtual environment in editable mode:

python -m pip install --editable ".[dev]"

Example

import asyncio

from chargefox import Bounds, ChargefoxClient


async def main() -> None:
    async with ChargefoxClient() as client:
        stations = await client.get_charge_stations_by_bounds(
            Bounds(south=-32.5, west=115.0, north=-31.0, east=116.5)
        )

        for station in stations:
            print(station.name, station.status, station.online)
            for connector in station.connectors:
                plug_name = connector.plug.short_name if connector.plug else "Unknown"
                print(plug_name, connector.status)

                if connector.active_charge_session:
                    session = connector.active_charge_session
                    charge_rate_kw = (
                        session.charge_rate.value_kw if session.charge_rate else None
                    )
                    consumption_kwh = (
                        session.total_consumption / 1000
                        if session.total_consumption is not None
                        else None
                    )
                    print(session.current_state, charge_rate_kw, consumption_kwh)


asyncio.run(main())

The current public queries do not require authentication. A bearer token can still be supplied for endpoints that require one:

client = ChargefoxClient(bearer_token="YOUR_TOKEN")

Behaviour

• get_locations_by_bounds() returns lightweight map summaries.
• get_locations_with_details_by_bounds() returns hydrated locations with their stations, connectors, plugs, and active sessions.
• get_charge_stations_by_bounds() collects station IDs from the lightweight summaries, then hydrates them through aliased root chargeStation(id) queries in batches of 10.
• get_charge_stations(station_ids) exposes the same batching publicly. Callers can pass only the stations they need refreshed, such as stations that remain enabled in Home Assistant. Input IDs are deduplicated while preserving order.
• Root station hydration returns rich station metadata, parent location details, pricing, idle fees, connectors, plugs, and active sessions. startMeterValue remains excluded from bulk polling because earlier session records caused HTTP 500 responses.
• Batch hydration uses at most 5 concurrent requests by default. Successful aliases are retained from partial GraphQL responses, and failed aliases are retried individually. If a whole batch fails, its station IDs fall back to individual queries. If every requested station ultimately fails, the first error is raised.
• HTTP 429 responses are retried three times by default. The client honors a numeric Retry-After header and otherwise uses 2/4/8-second exponential backoff.
• Requests are paced through a client-wide gate at a minimum interval of 0.25 seconds. A 429 pauses all workers, preventing concurrent retries from extending the limit.
• get_location(), get_charge_station(), and get_connector() support targeted polling.
• Active-session consumption is returned by the API in Wh; divide it by 1000 for kWh.

The concurrency and batch limits can be configured with ChargefoxClient(max_concurrent_requests=5, station_batch_size=10, location_batch_size=10). The location batch size applies to get_locations_with_details_by_bounds(). Rate-limit behavior can be configured with ChargefoxClient(max_rate_limit_retries=3, rate_limit_retry_delay=2). Request pacing can be configured with ChargefoxClient(min_request_interval=0.5).

Development checks

python -m ruff format --check .
python -m ruff check .
python -m unittest discover -s tests -v
python -m coverage run -m unittest discover -s tests
python -m coverage report

Build a wheel into dist/ with:

python -m pip wheel . --no-deps --wheel-dir dist

Live integration test

Set CHARGEFOX_RUN_LIVE_TESTS=1, then run the normal test suite. The live tests use the public API without authentication and are skipped unless explicitly enabled.

py -m unittest discover -s tests

If you need to override the endpoint, set CHARGEFOX_GRAPHQL_URL as well.

The live tests cover lookup collections, lightweight map discovery, and resolving a full location and its stations from a map result. Connector status and active-session data are included with each full station and can be refreshed by polling the location, station, or connector methods.