worldtolls API

Calculate toll costs for routes across Turkey, Greece, Bulgaria, Albania, North Macedonia, Serbia and Montenegro directly from your own app, dispatch system or fleet-management platform — send us two points (or a full multi-stop itinerary) and vehicle class, we return the toll cost, broken down by country and gate, in both the original currency and TRY. worldtolls runs its own lightweight gateway in front of the underlying calculation engine, so you get a simple, stable request/response shape without needing to know anything about the engine behind it.

• Getting started
• Quickstart
• Base URL
• Authentication
• Rate limits & country coverage
• Versioning & stability
• Requests
• Vehicle classes
• Vehicle profile (optional)
• Endpoints
• POST /toll
• POST /toll/multi
• Response reference
• Full response field reference
• Currency conversion
• Reference
• Errors
• Recommended integration flow
• FAQ

Quickstart

The fastest path from zero to a priced route, once you have a key (see the box above):

curl -X POST https://worldtolls.com/gateway/toll \
  -H "X-API-Key: wtk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "lat": 41.0082, "lon": 28.9784 },
    "to":   { "lat": 40.6401, "lon": 22.9444 }
  }'

That's it — from/to are the only required fields. Everything else (vehicle_class, vehicle_profile) has a safe default. Read result.toplam_genel_tl for the grand total in TRY, and check result.eksiksiz — see POST /toll below for the full response shape and what every field means.

Base URL

Authentication

Send your key in an X-API-Key header on every request that needs one (see the endpoint table below). Your key looks like wtk_... — it's generated by worldtolls itself the moment your API access is approved, and you can view/copy it any time from My account. It is not a ucretliyol.com key: it's issued and validated entirely by worldtolls' own database, and it only works against worldtolls' own endpoints below.

curl -H "X-API-Key: wtk_your_key_here" https://worldtolls.com/gateway/status

Rate limits & country coverage

Each plan has an hourly and a monthly request limit, and access to a specific set of countries — see Pricing for the exact numbers for your plan, or check your live usage any time in My account (it shows your limit and how much you've used this hour and this month, updated in real time). Requesting a country your plan doesn't include simply won't appear in the response — it isn't an error, the relevant fields (and that country's share of the total) are just omitted. Exceeding your limit returns 429 with "error": "rate_limit_exceeded".

Versioning & stability

The gateway doesn't use a version number in the URL (no /v1/) — there's one live version of the API, and we intend to keep changes to it backward-compatible: existing fields keep their name, type and meaning, and new fields (like vehicle_profile, dikkat and eksiksiz — all added 16.09.2026) are additive. Code that only reads the fields it needs and ignores unknown ones will keep working across changes. If a genuinely breaking change is ever needed, we'll announce it and give existing integrations a migration window rather than changing behavior underneath you silently.

Vehicle classes

Send the class that matches the vehicle as vehicle_class (an integer, 1–6). It's applied consistently across every country in the response. Omit it and it defaults to 1.

Vehicle profile (optional)

16.09.2026: some routes cross toll structures that price by more than just the generic vehicle_class — for example a multi-category bridge with its own height/axle/seat brackets (Greece's Rio–Antirrio bridge has 9 such categories), or Bulgaria's heavy-vehicle e-vignette system, which prices by emission class and tonnage bracket rather than a single generic class. If you omit vehicle_profile entirely, nothing changes for you — the engine falls back to its existing safe defaults for your vehicle_class, exactly as before this field existed. Send whichever of these fields you actually know; every field is independently optional.

Example — a 45-seat coach crossing Rio–Antirrio

{
  "from": { "lat": 38.325, "lon": 21.782 },
  "to":   { "lat": 38.335, "lon": 21.740 },
  "vehicle_class": 3,
  "vehicle_profile": { "seats": 45, "height_m": 3.9 }
}

An invalid bg_category, bg_emission_class or bg_co2_class value is rejected up front with HTTP 400 and a valid_values array listing exactly what's accepted — see Errors. There's nothing to validate for the other fields; any number/boolean is accepted as given.

Endpoints

POST /toll

Calculates the toll cost of driving from one point to another, across every country your plan covers along the way. This is the endpoint for the common case: you already know (or your own map/navigation stack already computed) the start and end point of a trip, and just need the toll cost for it.

cURL

curl -X POST https://worldtolls.com/gateway/toll \
  -H "X-API-Key: wtk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "lat": 41.0082, "lon": 28.9784 },
    "to":   { "lat": 40.6401, "lon": 22.9444 },
    "vehicle_class": 1
  }'

Node.js (fetch)

const res = await fetch('https://worldtolls.com/gateway/toll', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WORLDTOLLS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: { lat: 41.0082, lon: 28.9784 },
    to:   { lat: 40.6401, lon: 22.9444 },
    vehicle_class: 1,
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(`${data.error}: ${data.message}`);
console.log(data.result.toplam_genel_tl);

Python (requests)

import os, requests

resp = requests.post(
    "https://worldtolls.com/gateway/toll",
    headers={"X-API-Key": os.environ["WORLDTOLLS_API_KEY"]},
    json={
        "from": {"lat": 41.0082, "lon": 28.9784},
        "to":   {"lat": 40.6401, "lon": 22.9444},
        "vehicle_class": 1,
    },
    timeout=10,
)
data = resp.json()
if not data["ok"]:
    raise RuntimeError(f"{data['error']}: {data['message']}")
print(data["result"]["toplam_genel_tl"])

A real response has more fields than most integrations need day-to-day — the table below covers the ones you'll use for a typical domestic + one-foreign-country trip. Full response field reference below documents every field this endpoint can return, including the ones omitted here for brevity (per-country breakdowns for all 6 non-Turkey countries, the route polyline, alternate routes, and the multi-category facility fields).

{
  "ok": true,
  "result": {
    "mesafe_km": 690.4,
    "sure_dk": 428.6,
    "toplam": 210.50,
    "giseler": [ ... ],
    "yurtdisi": { "toplam_tl": 38.20, ... },
    "toplam_genel_tl": 248.70,
    "izinli_ulkeler": ["TR", "GR"],
    "eksiksiz": true,
    "dikkat": []
  }
}

Country-specific sections (e.g. the Greece leg above, under yurtdisi) are simply omitted from the response if your plan doesn't include that country, rather than erroring. The same applies to Bulgaria/Albania/North Macedonia/Serbia/Montenegro's own sections (bulgaristan/arnavutluk/makedonya/sirbistan/karadag) — see the field reference for their exact shape.

Example — dikkat when a multi-category structure needs more detail

{
  "ok": true,
  "result": {
    "toplam_genel_tl": 210.50,
    "eksiksiz": false,
    "dikkat": [
      {
        "tip": "vehicle_profile_needed",
        "facility": "Rio-Antirrio Köprüsü",
        "message": "This route crosses \"Rio-Antirrio Köprüsü\", which needs more vehicle detail to price accurately for your vehicle class. Its fee is NOT included in toplam_genel_tl below. Send it via vehicle_profile and retry.",
        "field_needed": "yukseklik",
        "options": ["<=2m", ">2m"]
      }
    ]
  }
}

In this example the bridge's fee is simply missing from toplam_genel_tl until you resend the request with, e.g., "vehicle_profile": {"height_m": 3.9} (or whichever field field_needed names).

POST /toll/multi

Same idea as /toll, but for a route with one or more stops in between — send an ordered array of 3 or more points (start, one or more stops, destination) and each consecutive pair is priced as its own leg, then summed into one total. Useful for delivery routes, multi-city trips, or any itinerary you build one stop at a time. Available on every plan, no separate "multi-stop" add-on needed.

cURL

curl -X POST https://worldtolls.com/gateway/toll/multi \
  -H "X-API-Key: wtk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "waypoints": [
      { "lat": 41.0082, "lon": 28.9784 },
      { "lat": 40.1885, "lon": 29.0610 },
      { "lat": 39.9334, "lon": 32.8597 }
    ],
    "vehicle_class": 1
  }'

Python (requests)

resp = requests.post(
    "https://worldtolls.com/gateway/toll/multi",
    headers={"X-API-Key": os.environ["WORLDTOLLS_API_KEY"]},
    json={
        "waypoints": [
            {"lat": 41.0082, "lon": 28.9784},
            {"lat": 40.1885, "lon": 29.0610},
            {"lat": 39.9334, "lon": 32.8597},
        ],
        "vehicle_class": 1,
    },
    timeout=10,
)
data = resp.json()

{
  "ok": true,
  "result": {
    "leg_count": 2,
    "total_distance_km": 471.8,
    "toplam_genel_tl": 238.10,
    "eksiksiz": true,
    "dikkat": [],
    "legs": [ { "mesafe_km": 95.4, "toplam_genel_tl": 40.00, ... }, { ... } ]
  }
}

vehicle_profile is accepted on /toll/multi exactly like on /toll — send it once at the top level and it's applied to every leg.

Full response field reference

Every field POST /toll can return (a /toll/multi leg is shaped identically). Field names are in Turkish — worldtolls is built for both Turkish and international customers and the calculation engine underneath predates the English docs — but every field's meaning and unit is given here in full, so you never have to guess. Fields not listed weren't found in any real response and shouldn't be relied on.

Top level (result)

giseler[] item — Turkish toll gate/bridge crossing

yurtdisi — Greece (GR)

Present only if the route enters Greece and your plan includes GR.

bulgaristan — Bulgaria (BG)

Present only if the route enters Bulgaria's tolled network and your plan includes BG. Absent for vehicle_class: 6 (motorcycle — exempt). Has two different shapes depending on tip: heavy vehicles use distance-based tolling, everyone else uses a flat e-vignette.

tip: "toll" (heavy vehicle, distance-based e-toll)

tip: "vinyet" (light vehicle, flat e-vignette)

arnavutluk — Albania (AL)

makedonya — North Macedonia (MK)

sirbistan — Serbia (RS)

karadag — Montenegro (ME)

Montenegro's tariffs are EUR-native — unlike AL/MK/RS there's no local-currency field.

tesis_gecisleri[] item — multi-category special facility

E.g. Greece's Rio–Antirrio bridge. Top-level, not nested in any country object — see the note in the top-level table above.

A facility that can't yet be auto-resolved for your vehicle appears in dikkat (tip: "vehicle_profile_needed") instead — see POST /toll above and Vehicle profile.

Currency conversion

Every non-TRY total in the response (toplam_tl fields, and by extension toplam_genel_tl) is converted to TRY server-side, using the rate returned alongside it (eur_kur, lek_kur, denar_kur, rsd_kur) — you don't need your own exchange-rate source to get a TRY total, but if you show the original-currency amount too (e.g. toplam_eur), use the accompanying rate field for consistency rather than a rate from elsewhere.

Errors

Every error response has the shape { "ok": false, "error": "...", "message": "..." }.

Recommended integration flow

1. Request access from My account and wait for approval — your wtk_... key appears there automatically once approved.
2. Call GET /status first (no key needed) to confirm you can reach the gateway from your network/server before wiring up authentication.
3. Call POST /toll with a route you already know the answer for (e.g. a short domestic trip) and sanity-check the response shape and totals against what you expect.
4. Handle the error shapes from the Errors table explicitly — at minimum 401 (bad key), 429 (back off and retry later), and 502 (transient, safe to retry with backoff).
5. Check eksiksiz/dikkat on every response rather than only reading toplam_genel_tl — see POST /toll.
6. Switch to real traffic, and keep an eye on My account for your live hourly/monthly usage so you can see a plan upgrade coming before you hit 429s.

Frequently asked questions

What happens if my route doesn't touch a tolled road at all?
You still get a normal 200 response — the relevant totals are just 0.

Is there a free/sandbox key for testing?
The Trial plan (see Pricing) is meant for exactly this — a real key with a small country selection and a low request limit, no separate sandbox mode.

Can I request a country that isn't in my plan just to see what happens?
Yes — it's not an error. The response simply won't include that country's section (see POST /toll above), so it's safe to always send the full trip and let the gateway filter it.

Does upgrading or changing my plan change my existing key?
No — your wtk_... key stays the same; only your limits and country access change once an admin approves the new plan.

My plan changed but I still see the old limits — why?
A plan or country change takes effect once our team approves the request in the panel, not the moment you submit it — check My account for the current status.

Can toplam_genel_tl ever be missing a fee without me knowing?
No — check eksiksiz on every response. It's false whenever anything (a multi-category structure that needed more vehicle_profile detail, or a gate pair that didn't match) was left out of the total, and dikkat tells you exactly what and why. When eksiksiz is true, the total is complete.

Do I have to send vehicle_profile on every request?
No. It's entirely optional — omit it and the engine uses its existing safe defaults for your vehicle_class, exactly like before this field was added. Only send it when you actually know the detail (e.g. a fleet system that already tracks vehicle height/seats), or when a previous response's dikkat asked for it.

Why are the response field names Turkish (toplam, giseler, mesafe_km) when the docs are in English?
worldtolls is built for both Turkish and international integrators, and the calculation engine's field names predate this English documentation. Rather than adding a translation layer that could drift out of sync with the real API, the full field reference above documents every Turkish field name's exact English meaning and unit — treat that table as the authoritative glossary.

Can I get the route as a polyline to draw on a map?
Yes — result.rota. Note its coordinate order is [longitude, latitude], the opposite of the request format — see the callout in the field reference.

Need a higher limit, more countries, or help integrating? Email info@worldtolls.com.