tollcalc 0.1.0

Python client and CLI for the TollCalc European truck toll API

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 full 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)

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

  --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,
    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
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: [e-mail]