Metadata-Version: 2.4
Name: tollcalc
Version: 0.3.0
Summary: Python client and CLI for the TollCalc European truck toll API
Project-URL: Homepage, https://tollcalc.eu
Project-URL: API, https://tollcalc.eu/en/api.html
Project-URL: Source, https://github.com/logenios/tollcalc-python
Author-email: Logenios Services GmbH <support@tollcalc.eu>
License: MIT
License-File: LICENSE
Keywords: europe,logistics,maut,toll,transport,truck
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# tollcalc

Python client and CLI for the [TollCalc](https://tollcalc.eu) European truck toll API.
Calculate road tolls for heavy goods vehicles across 37 European countries — by address or GPS coordinates.

## Installation

```bash
pip install tollcalc
```

## Authentication

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

### Log in via browser (recommended)

```bash
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.

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

### Set the token manually

```bash
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:

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

With a via stop in Munich and segment detail:

```bash
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`:

```bash
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:

```bash
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

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

```python
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**:

```python
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

```python
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](https://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
