tollcalc

Python client and CLI for the TollCalc European truck toll API. Calculate road tolls for heavy goods vehicles across 37 European countries — by address or GPS coordinates.

Installation

pip install tollcalc

Authentication

Up to 10 requests per month are free without a token.

Log in via browser (recommended)

tollcalc auth login

This opens your browser, lets you log in to your TollCalc account, and saves a long-lived API token to ~/.config/tollcalc/token. All subsequent CLI calls use this token automatically.

tollcalc auth status    # show current login state
tollcalc auth logout    # remove the stored token

Set the token manually

export TOLLCALC_TOKEN=your_token_here

Or write it to ~/.config/tollcalc/token.

---

CLI usage

Route by address

Calculate the toll for a truck driving from Hamburg to Vienna:

tollcalc --from "Hamburg, Germany" --to "Vienna, Austria"

With a via stop in Munich and segment detail:

tollcalc \
  --from "Hamburg, Germany" \
  --to   "Vienna, Austria" \
  --via  "Munich, Germany" \
  --axles 5 \
  --weight 40 \
  --emission-class euro6 \
  --co2-class class_1 \
  --all-segs

Output:

Route: Hamburg → Munich → Vienna
Total: 983.4 km  |  Toll: 142.78 €
Vehicle: 5 axles, 40 t, euro6, class_1

 Country      Total km   Toll km   Distance   Traversal      Total    €/km   Segs
 Germany       512.3 km   498.1 km    82.40 €          -    82.40 €  0.1655    43
 Austria       211.8 km   211.8 km    50.38 €     10.00 €   60.38 €  0.2843    18

Route by GPS coordinates

If you have a GPS track from a driven route (e.g. from a telematics system), pass the coordinates directly — geocoding is skipped and the toll is calculated on the exact driven path.

Use "lat;lon" format for each point. Pass the first point as --from, the last as --to, and all intermediate points via --via:

tollcalc \
  --from "53.5503;10.0006" \
  --via  "52.5200;13.4050" \
  --via  "50.0755;14.4378" \
  --via  "48.8068;14.0059" \
  --to   "48.2093;16.3728"

Waypoint limit: 50 total (origin + via + destination) The routing engine accepts at most 50 waypoints per request, which means --via may contain at most 48 entries. Raw GPS tracks from telematics systems typically have hundreds or thousands of points — these must be downsampled before use. A good rule of thumb: keep one point per kilometre. A 500 km route should have around 50 via points or fewer. Many telematics platforms offer a built-in downsampling or track simplification feature (e.g. Ramer-Douglas-Peucker algorithm).

You can also mix addresses and coordinates freely:

tollcalc --from "Hamburg, Germany" --to "48.2093;16.3728"

All options

  --from PLACE          Origin: address or "lat;lon" coordinate
  --to   PLACE          Destination: address or "lat;lon" coordinate
  --via  PLACE          Via waypoint, repeatable

  --axles N             Number of axles (default: 5)
  --weight T            Gross weight in tonnes (default: 40)
  --emission-class K    Euro emission class, e.g. euro6 (default: euro6)
  --co2-class K         CO2 class class_1..class_5 (default: class_1)

  --planned-trip-start  DATETIME   Trip date/datetime (ISO-8601) — uses the toll
                        rules valid at that point in time (default: now)

  --token TOKEN         API bearer token (or set TOLLCALC_TOKEN)
  --api-url URL         Custom API base URL

  --segs                Show tolled segments per country
  --all-segs            Show all segments, including toll-free ones
  --road-types          Show road-type breakdown per country
  --json                Print raw API response as JSON
  --debug               Request ORS routing debug data
  --ors FILE            Save raw ORS response to FILE (implies --debug)
  --ors-steps           Print ORS step-by-step road analysis (implies --debug)

---

Python API

Use calculate_toll() when you want to integrate toll calculation into your own Python application without using the CLI.

Route by address

from tollcalc import calculate_toll

result = calculate_toll(
    origin="Hamburg, Germany",
    destination="Vienna, Austria",
    via=["Munich, Germany"],
    axles=5,
    weight=40.0,
    emission_class="euro6",
    co2_class="class_1",
)

print(f"Total toll: {result['total_toll_eur']:.2f} €")
print(f"Total distance: {result['total_distance_km']:.1f} km")

for country in result["countries"]:
    print(f"  {country['country_name']}: {country['toll_eur']:.2f} €")

Local currency and VAT

Every country entry contains the original local-currency amounts alongside the EUR values, so you never have to re-derive them from the exchange rate:

Field	Meaning
toll_eur / toll_local	Gross toll (VAT included where applicable) in EUR / local currency
toll_eur_net / toll_local_net	Net toll (excluding VAT)
toll_eur_vat / toll_local_vat	VAT share (gross − net)
currency	ISO 4217 local currency code (e.g. PLN)
currency_rate	EUR per 1 unit of local currency (local = EUR / currency_rate)

Per-segment details (countries[].segments[]) expose the same toll_local* fields. In countries where the toll is a public levy without VAT (e.g. Poland's e-TOLL, Germany, Czechia), vat_applicable is false and toll_local_net == toll_local; the private concession sections (e.g. A1 AmberOne, A4 Stalexport) keep 23 % VAT.

Route by GPS coordinates

If your TMS or telematics system provides a GPS track, pass the coordinates as "lat;lon" strings. This is useful when you want to calculate the toll for a route that has already been driven:

from tollcalc import calculate_toll

# GPS track recorded by the vehicle (lat;lon format)
gps_track = [
    "53.5503;10.0006",   # Hamburg
    "52.5200;13.4050",   # Berlin
    "50.0755;14.4378",   # Prague
    "48.8068;14.0059",   # Linz area
]

result = calculate_toll(
    origin=gps_track[0],
    destination=gps_track[-1],
    via=gps_track[1:-1],   # all intermediate points
    axles=5,
    weight=40.0,
    emission_class="euro6",
    co2_class="class_1",
    token="your_api_token",   # or set TOLLCALC_TOKEN env var
)

print(f"Total toll for driven route: {result['total_toll_eur']:.2f} €")

for country in result["countries"]:
    km_toll   = country["km_toll_eur"]
    traversal = country["traversal_toll_eur"]
    print(
        f"  {country['country_name']:15s}  "
        f"{country['total_km']:6.1f} km  "
        f"{country['toll_eur']:7.2f} €"
        + (f"  (incl. {traversal:.2f} € vignette)" if traversal else "")
    )

Function reference

calculate_toll(
    origin: str,
    destination: str,
    *,
    via: list[str] | None = None,
    axles: int = 5,
    weight: float = 40.0,
    emission_class: str = "euro6",
    co2_class: str = "class_1",
    token: str | None = None,
    api_url: str = "https://app.tollcalc.eu",
    debug: bool = False,
    planned_trip_start: str | None = None,
    sub_account: str | None = None,
    timeout: int = 60,
) -> dict

Parameter	Description
origin	Departure — free-text address or "lat;lon" string
destination	Arrival — free-text address or "lat;lon" string
via	List of intermediate waypoints (addresses or coordinates). Max 48 entries — the routing engine allows at most 50 waypoints in total (origin + via + destination). For GPS tracks, downsample to ~1 point/km.
axles	Number of axles: 2, 3, 4, 5 (5 = 5+)
weight	Gross vehicle weight in tonnes
emission_class	euro0 … euro6
co2_class	class_1 (highest emissions) … class_5 (zero emission)
token	API bearer token. Falls back to TOLLCALC_TOKEN env var or ~/.config/tollcalc/token
api_url	Custom API base URL (default: https://app.tollcalc.eu)
debug	Include raw ORS routing data in the response
planned_trip_start	ISO-8601 date or datetime (e.g. "2026-09-01" or "2026-09-01T06:00:00Z"). Uses the toll rules that are valid at this point in time (e.g. the Dutch 22.3 % discount from 1 Sep 2026). Default: current time
sub_account	Optional usage attribution label, sent as the X-Subaccount HTTP header (e.g. a client company or department). Max 64 chars, allowed A-Z a-z 0-9 _ : -. Default: none (API attributes to "Default")
timeout	HTTP timeout in seconds

Returns the raw API response dict. Raises requests.HTTPError on API errors.

---

Supported countries

37 European countries including Germany, Austria, France, Poland, Czech Republic, Hungary, Romania, Croatia, Benelux, Scandinavia, and more. See tollcalc.eu for the full list.

Links

• API documentation: https://tollcalc.eu/en/api.html
• Web app: https://app.tollcalc.eu
• Support: support@tollcalc.eu