Toll Plaza Rates API
New
Find the published toll rates for a plaza by its code, its name or its state, and use them to price routes, quote freight and check toll charges.
Overview
Every toll plaza on India's national highways publishes its fares, by vehicle class and by type of journey, and revises them on a set date. Logistics companies, transport operators and route-planning products need those fares to quote a trip, budget a route or check a toll charge. Copying them from a portal one plaza at a time is slow, and a copy goes out of date when the rates are revised. Your application sends a plaza code, a plaza name or a state, and gets back each matching plaza with its location, the date its rates took effect and its published fares by vehicle class, as structured data.
- Category
- Vehicle Services
- Coverage
- Toll plazas in the national toll catalogue, with their published fares
- Input
- Toll plaza code, toll plaza name or state
- Output
- Matching plazas with code, name, state, coordinates, rates effective date and fares by vehicle class
- Typical users
- Freight and logistics companies, transport operators, route-planning products, finance teams
- Coverage note
- Plazas in the national toll catalogue; a plaza that publishes no fares is returned without rates
The overview and the sections after the reference are the FinSour API catalog’s own record for this service, rendered unaltered.
Endpoint URL and method
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Authentication
Send your API key in this header on every call, from your own server: a key sent from a browser is refused. A key starting fs_test_ calls the sandbox and one starting fs_live_ calls production, at the same address. Create keys in the FinSour console.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Request parameters
Headers
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
Idempotency-Key | string | Required | A key you generate for each attempt. Sending the same key again returns the first answer instead of running the check twice; the same key with a different body is refused. | 8 to 255 characters. Matches ^[A-Za-z0-9._:-]+$ |
Body
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
input | object | Required | The details to check. | — |
input. | string | Optional | — | Matches ^[0-9]{1,7}$ |
input. | string | Optional | — | Matches ^[A-Za-z0-9@#$%^&*()_+!.,":;?\- ]+$. 1 to 200 characters |
input. | string | Optional | — | Matches ^[A-Za-z0-9@#$%^&*()_+!.,":;?\- ]+$. 1 to 200 characters |
options | object | Optional | Settings for this call. | — |
options. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
options. | object | Optional | The person's consent to this check. | — |
options. | boolean | Required | Send true once the person has agreed to the check. | Always true |
options. | string (date-time) | Required | When the person gave consent. | — |
options. | string | Required | What the check is for, for example kyc. | 1 to 64 characters |
Request samples
cURL
curl -X POST https://gateway.staging.finsour.io/v1/logistics/toll-plaza-rates \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"input": {
"tollPlazaCode": "<tollPlazaCode>"
}
}'Node.js
const response = await fetch("https://gateway.staging.finsour.io/v1/logistics/toll-plaza-rates", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"input": {
"tollPlazaCode": "<tollPlazaCode>"
}
}),
});
console.log(response.status, await response.json());Python
import os
import uuid
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/logistics/toll-plaza-rates",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"input": {
"tollPlazaCode": "<tollPlazaCode>",
},
},
timeout=30,
)
print(response.status_code, response.json())Generated from the fields above. Replace each value in angle brackets with your own; the key is read from FINSOUR_API_KEY.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Response schema
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
data | object | Always | The result of the check. | — |
data. | boolean | Always | — | — |
data. | string or any or null | Always | The plaza code sent; null when the lookup was by name or by state. | — |
data. | string or any or null | Always | The plaza name sent; null when the lookup was by code or by state. | — |
data. | string or any or null | Always | The state sent; null when the lookup was by code or by name. | — |
data. | array of objects | Always | The plazas found: one for a code, the matches for a name, every plaza in the state for a state. | — |
data. | string or any or null | Always | The plaza's numeric code, without leading zeros: the source states it as a number. | — |
data. | string or null | Always | The plaza's name as the national toll catalogue spells it. | — |
data. | string or null | Always | The state the plaza is in, as the catalogue spells it. | — |
data. | number or null | Always | The plaza's latitude in decimal degrees. | Minimum -90. Maximum 90 |
data. | number or null | Always | The plaza's longitude in decimal degrees. | Minimum -180. Maximum 180 |
data. | string or any or null | Always | The date the published rates took effect. | — |
data. | object or any or null | Always | The published fares by vehicle class; null when the plaza publishes none. | — |
data. | object | Always | — | — |
data. | string | Always | When the answer was fetched: RFC 3339 UTC with a Z, never an epoch or an IST offset. | Matches ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Error codes
| Code | Status | Meaning | Retrying |
|---|---|---|---|
API_VERSION_UNSUPPORTED | 400 | That API version is no longer supported. | Do not retry automatically |
IDEMPOTENCY_KEY_INVALID | 400 | That Idempotency-Key does not meet the required format. | Do not retry automatically |
IDEMPOTENCY_KEY_REQUIRED | 400 | An Idempotency-Key header is required for this request. | Do not retry automatically |
REQUEST_MALFORMED | 400 | The request could not be parsed. | Do not retry automatically |
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
INSUFFICIENT_BALANCE | 402 | The available balance is not enough for this request. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
PRODUCT_NOT_AVAILABLE | 403 | That product is not available. | Do not retry automatically |
PRODUCT_RETIRED | 403 | That product has been withdrawn. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
PRODUCT_NOT_FOUND | 404 | No such product. | Do not retry automatically |
IDEMPOTENCY_KEY_REUSED | 409 | That idempotency key was already used for a different request. | Do not retry automatically |
PRICE_UNAVAILABLE | 409 | No active price covers this product right now. | Safe to retry |
REQUEST_IN_PROGRESS | 409 | An earlier attempt with this key is still running. | Safe to retry |
SETTLEMENT_PENDING | 409 | This request is awaiting reconciliation by an operator. | Do not retry automatically |
API_VERSION_SUNSET | 410 | That API version passed its announced sunset date. | Do not retry automatically |
REQUEST_TOO_LARGE | 413 | The request body is too large. | Do not retry automatically |
UNSUPPORTED_MEDIA_TYPE | 415 | That content type is not accepted on this route. | Do not retry automatically |
SANDBOX_FIXTURE_MISSING | 422 | No sandbox fixture exists for this input. Use a different test value. | Do not retry automatically |
UPSTREAM_REJECTED | 422 | The upstream source rejected the input. | Do not retry automatically |
VALIDATION_FAILED | 422 | The request payload is invalid. | Do not retry automatically |
CONCURRENCY_LIMIT | 429 | Too many simultaneous requests. | Safe to retry |
QUOTA_EXCEEDED | 429 | The allowance for this window is spent. | Do not retry automatically |
RATE_LIMITED | 429 | Too many requests. | Safe to retry |
INTERNAL_ERROR | 500 | An unexpected error occurred. | Safe to retry |
OUTCOME_UNCERTAIN | 502 | The outcome of this request is not yet known. Retry with the same Idempotency-Key. | Do not retry automatically |
UPSTREAM_UNAVAILABLE | 502 | The upstream source is unavailable. Retry shortly. | Safe to retry |
MAINTENANCE_MODE | 503 | The service is in a maintenance window. | Safe to retry |
NO_PROVIDER_AVAILABLE | 503 | No provider can serve this product right now. | Safe to retry |
SERVICE_OVERLOADED | 503 | The service is shedding load. Retry shortly. | Safe to retry |
UPSTREAM_TIMEOUT | 504 | The upstream source did not respond in time. | Safe to retry |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Rate limits
| Scope | Limit | Window | At the limit |
|---|---|---|---|
| Your API key, within your organisation's limit | The figure in X-RateLimit-Limit | Per minute | 429 RATE_LIMITED, with Retry-After in seconds. Every answer past authentication carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Use cases
- Freight quoting: adding the tolls on a route to a customer quote
- Route planning: showing the toll cost of each route option
- Transport budgeting: costing a new route before it is scheduled
- Toll audits: checking a charged amount against the published fare
What this service does
Published fares by vehicle class
Each matching plaza with its fares for every vehicle class it publishes, from cars to vehicles with seven or more axles, and the date those rates took effect.
Find plazas three ways
Search by plaza code, by plaza name or by state. A state returns every plaza in it.
Location with every plaza
The plaza's latitude and longitude come back with its fares, so a route planner can place it on the route.
No personal data involved
The lookup is about toll plazas, not vehicles or people, so it needs no consent and carries no personal data.
How a check runs
Arrange access
Tell us where toll rates fit in your quoting or planning process. We arrange access for your organization under the applicable service contract.
Send a plaza code, name or state
Your application sends the identifier it holds for the plaza, or a state to list its plazas.
The rates are retrieved
The service finds the matching plazas in the national toll catalogue and reads their published fares.
Read the fares
Your application receives each plaza with its location, the effective date of its rates and its fares by vehicle class.
Price the route
Use the fare for the vehicle class the trip will use in your quote, budget or toll check.
Questions
- What do I send to look up toll plaza rates?
- A plaza code, a plaza name or a state. A state returns every plaza in it.
- What does the response include?
- Each matching plaza's code, name, state and coordinates, the date its rates took effect, and its published fares by vehicle class.
- How current are the rates?
- The response carries the date the published rates took effect. Fares are revised on set dates, so refresh any rates you keep after a revision.
- Do I need anyone's consent to look up toll rates?
- No. The lookup is about toll plazas and their published fares, not about a vehicle or a person.
- What if a plaza has no fares on record?
- The plaza is returned with its details and no rates, so your application can tell a plaza without published fares from one that was not found.
- How do I get access to the Toll Plaza Rates API?
- Start with Get API and tell us how toll rates fit your quoting or planning process, and what volumes you expect. We set up access under the applicable service contract.
Catalog entry last updated .