---
title: "Plan a trip from A to B through charging stops"
method: GET
path: "/v1/trips/plan"
---

# Plan a trip from A to B through charging stops

`GET /v1/trips/plan`

## Request

- Base URL: `https://api.chargealong.io`
- URL: `https://api.chargealong.io/v1/trips/plan`
- Auth: none required

Draws the road route, picks charging stops from the sites listed here, and says how long each stop takes. The car never arrives anywhere below the reserve the driver sets, including at the destination: a trip that cannot be made that way comes back as the stretch of road where it fails, never as a plan that breaks the reserve.

Australia and New Zealand for now. The router holds OpenStreetMap data for those two countries, so a trip elsewhere has no road route.

Coordinates are rounded to three decimal places, about 100 m, before anything is planned: a plan depends only on its inputs and the data, so it can be cached, and no exact position reaches a log or a cache key.

Times are estimates from a charging curve, not a promise: a charger may be busy, cold or broken when you arrive. Every stop carries its site's page, where the state of the record is written out.

## Query parameters

- `from` string, required
- `to` string, required
- `range_km` number, required
- `reserve` number
- `start` number
- `charge_to` number
- `battery_kwh` number
- `max_dc_kw` number
- `max_ac_kw` number
- `min_kw` number
- `connectors` string

## Response `200`

The route line, the stops in order with the charge in and out of each, and the totals. A trip that cannot meet the reserve answers here too, with feasible false and the gap named.

- TripPlanResponse: The answer, in the envelope every read shares.
  - `data` TripPlan, required: A trip: the road route and the stops that make it drivable.
    - `route` object, required: The road route.
      - `distance_km` number, required: Road distance, km.
      - `duration_min` integer, required: Driving time without charging, minutes.
      - `line` array[], required: The route as [longitude, latitude] pairs, GeoJSON order.
        - unknown[]
          - unknown
    - `feasible` boolean, required: Whether the trip can be driven with the stops given. False means a gap: a stretch with no charger in range.
    - `arrival_pct` integer: Battery on arrival, percent. Absent when the plan is not feasible.
    - `drive_min` integer, required: Minutes driving.
    - `charge_min` integer, required: Minutes charging.
    - `total_min` integer, required: Minutes in all, including a small allowance per stop.
    - `gap` TripGap: Where the car cannot reach a charger in range: the stretch of the route, in km from the start.
      - `from_km` number, required: Where the stretch starts.
      - `to_km` number, required: Where it ends.
    - `stops` TripStop[], required: Charging stops in order along the route.
      - `site` TripSite, required: A charging stop's site.
        - `public_id` string, required: The site's permanent id.
        - `name` string, required: The site's name.
        - `network` string, required: The network's slug.
        - `network_name` string: The network's display name.
        - `operator` string: Who operates it.
        - `address` string: Its street address.
        - `status` 'active' | 'unavailable' | 'planned' | 'removed', required: active: in service. unavailable: listed but reported out of service. planned: announced, not yet open. removed: gone from every source; the record stays so an old link still answers, and the page on the site answers 410.
        - `lat` number, required: Latitude.
        - `lng` number, required: Longitude.
        - `path` string, required: The page on https://chargealong.io this record is shown on, as a path: prefix it with https://chargealong.io.
      - `along_km` number, required: Kilometres along the route to the stop.
      - `detour_km` number, required: Extra kilometres off the route to reach it and come back.
      - `power_kw` number, required: Power the car will draw there, kW: the lower of the charger's and the car's.
      - `dc` boolean, required: Whether it is a DC charger.
      - `arrive_pct` integer, required: Battery on arrival, percent.
      - `depart_pct` integer, required: Battery on leaving, percent.
      - `energy_kwh` number, required: Energy added, kWh.
      - `charge_min` integer, required: Minutes charging.
  - `next_cursor` string: Present only on a paged list: pass it back to read the next page. No public read is paged today.
  - `generated_at` string, date-time, required: When this answer was generated, UTC. Answers are cached, so it can be up to an hour old.

## Other responses

- `400`: A parameter is missing, unreadable or outside its range. The problem names it.
- `422`: The problem "no road route between these points": the router found no road between them at all. A trip the car cannot make on the chargers available is not this: it answers 200 with feasible false and the gap named.
- `503`: The problem "trip planning is not available". Either the router is down, or it holds no map covering both points (Melbourne to London): the two are the same answer today. Everything else here is unaffected.

---

[API](https://skmtc.dev/chargealong/apis/chargealong-api.md) · [All operations](https://skmtc.dev/chargealong/apis/chargealong-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chargealong/apis/chargealong-api/revisions/f7968808e434?raw)