Integracja TollCalc z własną aplikacją

TollCalc można zintegrować z oprogramowaniem lub przepływami pracy AI na trzy sposoby:

Metoda	Najlepsza dla
REST API	Integracja serwer-serwer, własne backendy
MCP (Model Context Protocol)	Asystenci AI (Claude, Cursor, GPT i inne)
Pakiet Python `tollcalc`	Skrypty, data science, Jupyter Notebooks

REST API

Pełna dokumentacja API (OpenAPI 3.0) dostępna pod adresem:

tollcalc.eu/en/api.html

Szybki start

curl -X POST https://app.tollcalc.eu/api/calculate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TWÓJ_TOKEN_API" \
  -d '{
    "origin": "Munich, Germany",
    "destination": "Vienna, Austria",
    "vehicle": {
      "weight": 40,
      "axles": 5,
      "emission_class": "euro6",
      "co2_class": "class_1"
    }
  }'

Parametry

Parametr	Typ	Opis
`origin`	string	Punkt startowy: adres lub `"lat;lon"`
`destination`	string	Punkt docelowy: adres lub `"lat;lon"`
`via`	string[]	Opcjonalne punkty pośrednie (maks. 15)
`vehicle.weight`	number	Masa całkowita w tonach (np. 40)
`vehicle.axles`	integer	Liczba osi: 2, 3, 4 lub 5
`vehicle.emission_class`	string	Norma Euro: `euro0`–`euro6`
`vehicle.co2_class`	string	Klasa CO₂: `class_1` (standardowy diesel) do `class_5` (zeroemisyjny)

Uwierzytelnianie

Tokeny API dostępne po rejestracji na app.tollcalc.eu. Bez tokena dozwolone jest 10 bezpłatnych zapytań na sesję.

MCP – Integracja z asystentami AI

TollCalc obsługuje Model Context Protocol (MCP) i można go podłączyć bezpośrednio do narzędzi AI, takich jak Claude Desktop, Cursor lub inny kompatybilny asystent.

Endpoint

POST https://app.tollcalc.eu/mcp

Dostępne narzędzia

Narzędzie	Opis
`calculate_toll`	Oblicza opłaty drogowe dla trasy ciężarówki
`get_quota`	Sprawdza pozostały limit dla bieżącej sesji

Konfiguracja w Claude Desktop

Dodaj następujący wpis do konfiguracji Claude Desktop (claude_desktop_config.json):

Opcja A – OAuth (zalecane): Tylko URL, token nie jest potrzebny.

{
  "mcpServers": {
    "tollcalc": {
      "url": "https://app.tollcalc.eu/mcp"
    }
  }
}

Opcja B – Klucz API (do automatyzacji): Token ustawiony ręcznie, np. do integracji serwer-serwer.

{
  "mcpServers": {
    "tollcalc": {
      "url": "https://app.tollcalc.eu/mcp",
      "headers": {
        "Authorization": "Bearer TWÓJ_TOKEN_API"
      }
    }
  }
}

Bez konfiguracji dostępnych jest 10 bezpłatnych zapytań na sesję MCP (= na rozmowę) — konto nie jest wymagane. Po 10 zapytaniach Claude Desktop automatycznie otwiera przeglądarkę do logowania (OAuth 2.0). Po zalogowaniu obowiązuje limit wybranego planu. Tokeny API dla opcji B można utworzyć na app.tollcalc.eu.

Poziomy szczegółowości

Narzędzie calculate_toll obsługuje trzy poziomy szczegółowości za pomocą parametru detail:

Wartość	Zawartość
`compact` (domyślny)	Łączna opłata, km z opłatą, km bez opłaty, podział na kraje
`detailed`	Jak `compact`, plus koszty na segment (bez geometrii)
`full`	Jak `detailed`, plus współrzędne i informacje debugowe

Pola odpowiedzi

Wszystkie poziomy szczegółowości zawierają następujące pola:

Pole	Typ	Opis
`origin`	string	Rozwiązana nazwa miejsca startowego
`destination`	string	Rozwiązana nazwa miejsca docelowego
`total_toll_eur`	number	Łączna opłata drogowa w EUR
`total_distance_km`	number	Całkowita długość trasy w km
`toll_km`	number	Odcinki z opłatą w km
`toll_free_km`	number	Odcinki bezpłatne w km
`countries`	array	Zestawienie według kraju (country, country_name, total_km, toll_km, toll_eur)
`info_url`	string	Link do wyświetlenia obliczeń w aplikacji webowej TollCalc — w tym zaplanowanej trasy na mapie interaktywnej; do udostępnienia współpracownikom lub otwarcia w przeglądarce

Przy detail=detailed pole countries zawiera dodatkowo segments (odcinek: road, type, km, toll_eur). Przy detail=full segmenty zawierają współrzędne, source_url, matched_geofence i geometrię.

Pakiet Python `tollcalc`

Pakiet Python tollcalc opakowuje REST API i umożliwia korzystanie ze skryptów Python lub notebooków Jupyter.

Instalacja

pip install tollcalc

Użycie

from tollcalc import TollCalc

client = TollCalc(api_key="TWÓJ_TOKEN_API")

result = client.calculate(
    origin="Munich, Germany",
    destination="Vienna, Austria",
    weight=40,
    axles=5,
    emission_class="euro6",
    co2_class="class_1",
)

print(f"Łączna opłata: {result.total_toll_eur:.2f} EUR")
print(f"Dystans:       {result.total_distance_km:.1f} km")

for country in result.countries:
    print(f"  {country.country_name}: {country.toll_eur:.2f} EUR ({country.toll_km:.0f} km z opłatą)")

Dokumentacja pakietu

Pełna dokumentacja i przykłady dostępne na PyPI: pypi.org/project/tollcalc

Cennik i limity

Plan	Zapytania/miesiąc	Cena
Free (bez tokena)	10 na sesję MCP (= na rozmowę)	bezpłatny
Starter	do 500	od 9 €/miesiąc
Professional	do 5 000	od 49 €/miesiąc
Enterprise	bez limitu	na zapytanie

Wszystkie plany i aktualne ceny: tollcalc.eu/en/#pricing

W razie pytań dotyczących integracji: support@tollcalc.eu