API documentation

Read toll plazas, tariffs, concessions and corridors from your own software.

The API is built and tested but has not been launched yet, so the host below does not answer yet. This page describes version 1 as it will be released. The values in the examples are samples, not real tariffs.

Getting started

  1. Create a free account and confirm your email address.
  2. Create an API key from your account. The key is shown once, so copy it somewhere safe. If you lose it, revoke it and create a new one.
  3. Send the key in the Authorization header of every request.
curl "https://api.tollinfo.co.za/v1/plazas/PLZ-N3TC-MOOI" \
  -H "Authorization: Bearer YOUR_API_KEY"

The base URL is https://api.tollinfo.co.za/v1. All requests and responses use JSON in UTF-8. Dates are YYYY-MM-DD and timestamps are ISO 8601 in UTC. Use HTTPS: a key sent over plain HTTP can be read by anyone on the network.

The API only reads data (the two POST endpoints only calculate) and sends no CORS headers: call it from your server, not from a web page or app, so your key is never exposed. Every response carries X-Request-Id; quote it if you contact us about a problem.

We log every request for security and support: the time, request id, method, path, query string, status, which key was used, the IP address it came from and its User-Agent. We never log request bodies or other headers, and anything that looks like an API key is removed from a logged address first. Logs are kept for 90 days.

Authentication

Every endpoint needs an API key. Send it in either header:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

Keep your key secret. Use it from your server, not from a web page or mobile app. A key in the address (query string) is never accepted. If both headers are sent, Authorization wins.

StatusCodeMeaning
401UNAUTHORIZED_MISSING_KEYNo key in the Authorization or X-API-Key header.
401UNAUTHORIZED_INVALID_KEYThe key is malformed, does not exist or has been revoked. These look the same on purpose.
401UNAUTHORIZED_INACTIVE_USERThe account behind the key is suspended or unverified. If you change your email address your account is unverified until you confirm the new one, and your keys do not work in the meantime.

Limits

Free keys allow 60 requests per minute and 1,000 per day. The minute limit counts from the top of each minute (UTC) and the daily quota resets at midnight UTC. Every request that carries a key counts, whatever its outcome, but a request refused by the minute limit does not use up any of the day's quota. Every response tells you where you stand:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute.
X-RateLimit-RemainingRequests left in the current minute.
X-RateLimit-ResetUnix time when the current minute ends.
X-Quota-Daily-LimitRequests allowed per day.
X-Quota-Daily-RemainingRequests left until midnight UTC.

Past a limit, the API answers 429 with RATE_LIMIT_EXCEEDED or QUOTA_EXCEEDED and a Retry-After header giving the seconds to wait.

Responses

A successful response has "status": "success" and the result in data. Lists may also carry a pagination object.

{
  "status": "success",
  "data": { ... }
}

An error has "status": "error" and an error object with a stable code to test for. The message is for people and may change. field names the input at fault (or is null), request_id matches the X-Request-Id header, and details appears when there is more to say, such as the plaza codes a calculation could not price.

{
  "status": "error",
  "error": {
    "code": "TARIFF_NOT_AVAILABLE",
    "message": "No cash tariff is on file for class_4 on 2026-10-09 at: PLZ-N3TC-MOOI.",
    "field": null,
    "timestamp": "2026-10-09T18:20:00Z",
    "request_id": "5f2c8e0a91b34d7c",
    "details": { "plazas": ["PLZ-N3TC-MOOI"] }
  }
}

Vehicle classes

ValueClassExamples
class_1Light vehiclesMotorcycles, sedans, hatchbacks, bakkies and SUVs without heavy commercial trailers.
class_2Medium heavy vehiclesTwo-axle heavy vehicles such as single-rear-axle trucks, buses and large utility vans.
class_3Large heavy vehiclesThree- and four-axle freight trucks, coaches and rigid heavy vehicles.
class_4Extra heavy vehiclesFreight combinations with five or more axles, such as interlinks and superlinks.

Endpoints

MethodPathReturns
GET/healthWhether the API is running. Needs no key.
GET/concessionsThe concessionaires.
GET/plazasToll plazas, with filters and pages.
GET/plazas/{plazas_code}One plaza with its current tariffs.
GET/plazas/{plazas_code}/tariffsA plaza's tariffs on a given date.
GET/corridorsThe corridors.
GET/corridors/{corridors_code}/plazasThe plazas along a corridor, in order.
POST/corridors/{corridors_code}/calculateThe toll cost of a corridor or a section of it.
POST/calculator/customThe toll cost of any list of plazas.

Concessions

GET /concessions lists the concessionaires.

  • country (optional): ISO 3166-1 alpha-2 code, such as ZA or MZ.
  • status (optional): active (default) or suspended.

Plazas

GET /plazas lists active toll plazas, mainline gantries and ramps, ordered by route and then name. GET /plazas/{plazas_code} returns one plaza, whatever its status (active or decommissioned), with the tariffs in force today in South Africa; current_tariffs is null if no class has a tariff today.

  • route (optional): the road, such as N3.
  • concession (optional): a concession code, such as N3TC.
  • type (optional): mainline or ramp.
  • direction (optional): both, northbound, southbound, eastbound or westbound.
  • page (default 1) and per_page (default 100, at most 500). The list has a pagination object next to data; a page past the end is an empty list.

The plaza example below is the detail of one plaza (the list holds the same fields, without current_tariffs).

{
  "status": "success",
  "data": {
    "plazas_hash": "018f4a21-72a3-7ef1-8912-401189ac3404",
    "plazas_code": "PLZ-N3TC-MOOI",
    "plazas_name": "Mooi River Mainline",
    "route_number": "N3",
    "type": "mainline",
    "direction": "both",
    "concession_code": "N3TC",
    "currency_code": "ZAR",
    "coordinates": { "latitude": -29.2152, "longitude": 30.0034 },
    "nearest_town": "Mooi River",
    "status": "active",
    "current_tariffs": {
      "travel_date": "2026-10-11",
      "rates": {
        "class_1": { "cash_amount": 68.0, "etag_amount": 68.0, "effective_from": "2026-03-01", "effective_to": null },
        "class_2": { "cash_amount": 162.0, "etag_amount": 162.0, "effective_from": "2026-03-01", "effective_to": null },
        "class_3": { "cash_amount": 226.0, "etag_amount": 226.0, "effective_from": "2026-03-01", "effective_to": null },
        "class_4": { "cash_amount": 319.0, "etag_amount": null, "effective_from": "2026-03-01", "effective_to": null }
      }
    }
  }
}

Tariffs

GET /plazas/{plazas_code}/tariffs returns the rates in force on a date. Each class has its own effective_from and effective_to, because classes can change on different days. A class with no tariff on the date is left out; if there is none at all (or none for the class you asked for) the answer is 404 TARIFF_NOT_AVAILABLE. etag_amount is null when no e-tag rate is on file.

  • travel_date (optional): YYYY-MM-DD. Defaults to today in South Africa.
  • vehicle_class (optional): one of the vehicle classes above.

Corridors

GET /corridors lists the corridors. GET /corridors/{corridors_code}/plazas lists the plazas along one corridor, in order.

  • direction (required): northbound, southbound, eastbound or westbound, and one the corridor has plazas for (the error message lists them).
  • mandatory_only (optional): true (default) returns only the plazas you must pass. false adds ramps.

Cost of a corridor or a section

POST /corridors/{corridors_code}/calculate totals the tolls along a corridor and lists each plaza on the way. Name a start plaza, an end plaza, or both, to price only a section.

  • vehicle_class (required) and direction (required).
  • from_plaza and to_plaza (optional): plaza codes on the corridor. Both plazas are included in the total. from_plaza must come before to_plaza in the direction of travel, otherwise the API returns INVALID_SECTION. A section with no plazas in it is 422 NO_PLAZAS_ON_SECTION.
  • include_ramps (optional): true or false (a real JSON boolean). Defaults to false.
  • travel_date (optional): defaults to today in South Africa.
curl -X POST "https://api.tollinfo.co.za/v1/corridors/COR-JHB-DBN/calculate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_class": "class_4",
    "direction": "southbound",
    "from_plaza": "PLZ-N3TC-WILGE",
    "to_plaza": "PLZ-N3TC-MOOI",
    "travel_date": "2026-10-09"
  }'
{
  "status": "success",
  "data": {
    "corridors_code": "COR-JHB-DBN",
    "corridors_name": "Gauteng to Durban (N3 Freight Corridor)",
    "travel_date": "2026-10-09",
    "vehicle_class": "class_4",
    "direction": "southbound",
    "from_plaza": "PLZ-N3TC-WILGE",
    "to_plaza": "PLZ-N3TC-MOOI",
    "summary": {
      "plazas_count": 3,
      "concessions_crossed": ["N3TC"],
      "totals": [
        { "currency_code": "ZAR", "total_cash_cost": 878.0, "total_etag_cost": 878.0 }
      ]
    },
    "itinerary": [
      { "sequence_order": 2, "plazas_code": "PLZ-N3TC-WILGE", "plazas_name": "Wilge Mainline", "concession_code": "N3TC", "currency_code": "ZAR", "cash_amount": 305.0, "etag_amount": 305.0, "is_mandatory": true, "km_mark": 128.2 },
      { "sequence_order": 3, "plazas_code": "PLZ-N3TC-TUGELA", "plazas_name": "Tugela Mainline", "concession_code": "N3TC", "currency_code": "ZAR", "cash_amount": 254.0, "etag_amount": 254.0, "is_mandatory": true, "km_mark": 242.8 },
      { "sequence_order": 4, "plazas_code": "PLZ-N3TC-MOOI", "plazas_name": "Mooi River Mainline", "concession_code": "N3TC", "currency_code": "ZAR", "cash_amount": 319.0, "etag_amount": 319.0, "is_mandatory": true, "km_mark": 376.1 }
    ]
  }
}

summary.totals always lists one entry for each currency in the trip, usually one, and amounts in different currencies are never added together. A total_etag_cost is null when any plaza in that currency has no e-tag rate on file; it is never counted as zero.

If any plaza on the trip has no cash tariff for the class on the date, there is no answer, only 422 TARIFF_NOT_AVAILABLE with the plaza codes in error.details.plazas (the example under Responses). This is deliberate: a partial total could be mistaken for the real one.

Cost of any list of plazas

POST /calculator/custom totals the tolls for plaza codes you choose, for routes that are not on a corridor. It takes vehicle_class, plazas (1 to 100 plaza codes, in the order you pass them; a plaza listed twice is charged twice) and an optional travel_date. Only active plazas can be priced: codes that do not exist, or are decommissioned, give 404 PLAZA_NOT_FOUND with the codes in error.details.plazas. Totals and missing tariffs work as above, and the response lists each plaza under breakdown.

curl -X POST "https://api.tollinfo.co.za/v1/calculator/custom" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_class": "class_4",
    "travel_date": "2026-10-09",
    "plazas": ["PLZ-N3TC-DEOOR", "PLZ-N3TC-WILGE", "PLZ-N3TC-MOOI"]
  }'

Errors

StatusCodeMeaning
400INVALID_PAYLOADThe body is not a JSON object, or a field has the wrong type or shape (field says which).
400INVALID_PARAMETERA query parameter is not valid (field says which).
400INVALID_VEHICLE_CLASSvehicle_class is missing or is not class_1 to class_4.
400INVALID_DIRECTIONdirection is missing, not valid, or not one the corridor has.
400INVALID_TRAVEL_DATEThe date is not written as YYYY-MM-DD, or is not a real date.
400INVALID_SECTIONfrom_plaza or to_plaza is not on the corridor for that direction, or they are in the wrong order.
401UNAUTHORIZED_*See Authentication.
404ROUTE_NOT_FOUNDThere is no such endpoint.
404PLAZA_NOT_FOUNDNo plaza has that code (or, for a calculation, it is decommissioned).
404CORRIDOR_NOT_FOUNDThe corridor does not exist or is not active.
404TARIFF_NOT_AVAILABLE/plazas/{code}/tariffs only: no tariff is on file for the plaza (or the class) on that date.
405METHOD_NOT_ALLOWEDThat method is not allowed on the path. The Allow header lists the right ones.
413PAYLOAD_TOO_LARGEThe request body is over 64 KB.
422TARIFF_NOT_AVAILABLEA calculation: some plaza on the trip has no cash tariff for the class on the date. details.plazas lists them.
422NO_PLAZAS_ON_SECTIONA corridor trip with no plazas in it.
429RATE_LIMIT_EXCEEDEDMore requests than the per-minute limit. See Retry-After.
429QUOTA_EXCEEDEDThe daily allowance is used up. See Retry-After.
500INTERNAL_SERVER_ERRORSomething went wrong on our side. Quote the request_id.
503SERVICE_UNAVAILABLE/health only: the API cannot reach its database.

About the data

Tariffs are recorded from each concession's published tariff schedule and apply from their effective date. Use travel_date to get the rate in force on a given day; if you leave it out it is today in South Africa, because tariffs change at South African midnight. Amounts are in the plaza's currency_code, and cash and e-tag rates are given separately. The website's toll calculator follows the same rules and gives the same numbers.

Toll Info does not operate the toll plazas. Confirm an amount with the concession before you rely on it for billing.