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} €")

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,
    timeout: int = 60,
) -> dict

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