API documentation
Read toll plazas, tariffs, concessions and corridors from your own software.
Getting started
- Create a free account and confirm your email address.
- 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.
- Send the key in the
Authorizationheader 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.
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED_MISSING_KEY | No key in the Authorization or X-API-Key header. |
| 401 | UNAUTHORIZED_INVALID_KEY | The key is malformed, does not exist or has been revoked. These look the same on purpose. |
| 401 | UNAUTHORIZED_INACTIVE_USER | The 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:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute. |
X-RateLimit-Remaining | Requests left in the current minute. |
X-RateLimit-Reset | Unix time when the current minute ends. |
X-Quota-Daily-Limit | Requests allowed per day. |
X-Quota-Daily-Remaining | Requests 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
| Value | Class | Examples |
|---|---|---|
class_1 | Light vehicles | Motorcycles, sedans, hatchbacks, bakkies and SUVs without heavy commercial trailers. |
class_2 | Medium heavy vehicles | Two-axle heavy vehicles such as single-rear-axle trucks, buses and large utility vans. |
class_3 | Large heavy vehicles | Three- and four-axle freight trucks, coaches and rigid heavy vehicles. |
class_4 | Extra heavy vehicles | Freight combinations with five or more axles, such as interlinks and superlinks. |
Endpoints
| Method | Path | Returns |
|---|---|---|
| GET | /health | Whether the API is running. Needs no key. |
| GET | /concessions | The concessionaires. |
| GET | /plazas | Toll plazas, with filters and pages. |
| GET | /plazas/{plazas_code} | One plaza with its current tariffs. |
| GET | /plazas/{plazas_code}/tariffs | A plaza's tariffs on a given date. |
| GET | /corridors | The corridors. |
| GET | /corridors/{corridors_code}/plazas | The plazas along a corridor, in order. |
| POST | /corridors/{corridors_code}/calculate | The toll cost of a corridor or a section of it. |
| POST | /calculator/custom | The toll cost of any list of plazas. |
Concessions
GET /concessions lists the concessionaires.
country(optional): ISO 3166-1 alpha-2 code, such asZAorMZ.status(optional):active(default) orsuspended.
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 asN3.concession(optional): a concession code, such asN3TC.type(optional):mainlineorramp.direction(optional):both,northbound,southbound,eastboundorwestbound.page(default 1) andper_page(default 100, at most 500). The list has apaginationobject next todata; 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,eastboundorwestbound, and one the corridor has plazas for (the error message lists them).mandatory_only(optional):true(default) returns only the plazas you must pass.falseadds 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) anddirection(required).from_plazaandto_plaza(optional): plaza codes on the corridor. Both plazas are included in the total.from_plazamust come beforeto_plazain the direction of travel, otherwise the API returnsINVALID_SECTION. A section with no plazas in it is422 NO_PLAZAS_ON_SECTION.include_ramps(optional):trueorfalse(a real JSON boolean). Defaults tofalse.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
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_PAYLOAD | The body is not a JSON object, or a field has the wrong type or shape (field says which). |
| 400 | INVALID_PARAMETER | A query parameter is not valid (field says which). |
| 400 | INVALID_VEHICLE_CLASS | vehicle_class is missing or is not class_1 to class_4. |
| 400 | INVALID_DIRECTION | direction is missing, not valid, or not one the corridor has. |
| 400 | INVALID_TRAVEL_DATE | The date is not written as YYYY-MM-DD, or is not a real date. |
| 400 | INVALID_SECTION | from_plaza or to_plaza is not on the corridor for that direction, or they are in the wrong order. |
| 401 | UNAUTHORIZED_* | See Authentication. |
| 404 | ROUTE_NOT_FOUND | There is no such endpoint. |
| 404 | PLAZA_NOT_FOUND | No plaza has that code (or, for a calculation, it is decommissioned). |
| 404 | CORRIDOR_NOT_FOUND | The corridor does not exist or is not active. |
| 404 | TARIFF_NOT_AVAILABLE | /plazas/{code}/tariffs only: no tariff is on file for the plaza (or the class) on that date. |
| 405 | METHOD_NOT_ALLOWED | That method is not allowed on the path. The Allow header lists the right ones. |
| 413 | PAYLOAD_TOO_LARGE | The request body is over 64 KB. |
| 422 | TARIFF_NOT_AVAILABLE | A calculation: some plaza on the trip has no cash tariff for the class on the date. details.plazas lists them. |
| 422 | NO_PLAZAS_ON_SECTION | A corridor trip with no plazas in it. |
| 429 | RATE_LIMIT_EXCEEDED | More requests than the per-minute limit. See Retry-After. |
| 429 | QUOTA_EXCEEDED | The daily allowance is used up. See Retry-After. |
| 500 | INTERNAL_SERVER_ERROR | Something went wrong on our side. Quote the request_id. |
| 503 | SERVICE_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.