Toll Enroute API

Endpoint Overview

POST /api/v1/nhai/toll-enroute

Description

The Toll Enroute API is a comprehensive route planning and toll calculation service that provides detailed journey information between any two locations in India. This powerful endpoint calculates optimal routes while identifying all toll plazas along the way, providing precise toll costs based on vehicle type, travel duration, total distance, and exact toll plaza coordinates.

This API integrates real-time NHAI toll rate data with advanced routing algorithms to deliver accurate cost estimations and route planning capabilities. It's essential for logistics companies, fleet operators, and travel applications that need precise toll cost calculations and route optimization for commercial and personal vehicles.

Key Benefits

Complete Route Intelligence: Get comprehensive journey details including duration, distance, and all toll plazas with exact costs

Vehicle-Specific Pricing: Accurate toll calculations based on NHAI vehicle classification standards for precise cost estimation

Real-time Toll Data: Access current toll rates and plaza information directly from NHAI systems

Geospatial Accuracy: Precise latitude/longitude coordinates for each toll plaza enabling GPS integration and mapping

Use Cases

Logistics & Fleet Management

Travel & Transportation Apps

Navigation & Mapping Services

Route Cost Optimization: Calculate and compare multiple route options to minimize toll expenses for commercial fleets

Trip Budget Planning: Provide accurate toll cost estimates for logistics planning and customer quotations

Fleet Expense Tracking: Monitor and analyze toll expenses across different routes and vehicle types

Delivery Route Planning: Optimize delivery routes considering toll costs, distance, and time constraints

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication (JWT)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
source_state	String	Yes	Source state identifier in snake_case format (e.g., "uttar_pradesh")
source_name	String	Yes	Source city/location name (e.g., "ghazipur")
destination_state	String	Yes	Destination state identifier in snake_case format (e.g., "bihar")
destination_name	String	Yes	Destination city/location name (e.g., "patna")
vehicle_type	String	Yes	Vehicle type identifier for toll calculation (e.g., "4_to_6_axle")

Example Request

{
    "source_state": "uttar_pradesh",
    "source_name": "ghazipur",
    "destination_state": "bihar",
    "destination_name": "patna",
    "vehicle_type": "4_to_6_axle"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object holding all route and toll information
data.client_id	String	Unique identifier for this route calculation request
data.source_state	String	Echo of the source state from request
data.source_name	String	Echo of the source location from request
data.destination_state	String	Echo of the destination state from request
data.destination_name	String	Echo of the destination location from request
data.vehicle_type	String	Echo of the vehicle type from request
data.duration	String	Total travel time in human-readable format
data.distance	String	Total route distance with units
data.toll_plaza_details	Array[Object]	Array of toll plaza information objects
data.toll_plaza_details[].toll_plaza_name	String	Name of the toll plaza
data.toll_plaza_details[].cost	String	Toll cost for the specified vehicle type
data.toll_plaza_details[].toll_plaza_longitude	String	Longitude coordinate of toll plaza
data.toll_plaza_details[].toll_plaza_latitude	String	Latitude coordinate of toll plaza
status_code	Integer	HTTP status code (200 for successful requests)
success	Boolean	Indicates whether the request was successful
message	String	Human-readable response message
message_code	String	Internal message code indicating request status

Example Successful Response

{
    "data": {
        "client_id": "toll_enroute_oSRrvUpyPXhpRqflvmzU",
        "source_state": "uttar_pradesh",
        "source_name": "ghazipur",
        "destination_state": "bihar",
        "destination_name": "patna",
        "vehicle_type": "4_to_6_axle",
        "duration": "4 hour 53 mins",
        "distance": "195.2 km",
        "toll_plaza_details": [
            {
                "toll_plaza_name": "Kulhariya",
                "cost": "565",
                "toll_plaza_longitude": "84.76861",
                "toll_plaza_latitude": "25.58056"
            },
            {
                "toll_plaza_name": "Dalsagar",
                "cost": "525",
                "toll_plaza_longitude": "84.060688",
                "toll_plaza_latitude": "25.580548"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Same Source and Destination

Invalid Vehicle Type

Unauthorized Access

{
    "status_code": 400,
    "success": false,
    "message": "Source and destination can't be same",
    "message_code": null
}

Occurs when the provided source and destination location are same.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code or version control systems

Implement proper token refresh mechanisms to handle token expiration gracefully

Use HTTPS exclusively for all API communications to protect sensitive route and location data

Validate and sanitize all input parameters to prevent injection attacks

Implement rate limiting to prevent API abuse and ensure fair usage across applications

User Experience Guidelines

Cache route calculations for frequently requested routes to improve response times

Implement progressive loading for route details, showing basic info first then toll plaza details

Provide clear error messages when locations cannot be found, with suggested alternatives

Display toll costs in user's preferred currency format with proper formatting

Implement retry logic with exponential backoff for transient network failures

Show route calculation progress indicators for better user experience during processing

Code Samples

cURL

Python

Node.js

Related APIs

NHAI Toll State List API: Get available states for route planning to validate source and destination states

NHAI Vehicle Type API: Retrieve supported vehicle types for accurate toll calculations

Toll Plaza Information API: Get detailed information about specific toll plazas including facilities and contact details

Real-time Traffic API: Combine with traffic data for comprehensive route planning and time estimation

Fuel Cost Calculator API: Integrate fuel costs with toll costs for complete journey expense calculation

Compliance and Legal Considerations

This API provides official NHAI toll rate calculations and route information that must be used in accordance with Indian highway regulations. Toll rates returned are based on current NHAI pricing structures and may change periodically. Applications using this API for commercial purposes should ensure compliance with local transportation laws and regulations. The route calculations are for informational purposes and should not replace official navigation systems for safety-critical applications. Always verify toll costs at actual toll plazas as rates may vary due to operational changes or special circumstances.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/nhai/toll-enroute' \ --header 'Content-Type: application/json' \ --data-raw '{ "source_state": "uttar_pradesh", "source_name": "ghazipur", "destination_state": "bihar", "destination_name": "patna", "vehicle_type": "4_to_6_axle" }'

{ "data": { "client_id": "toll_enroute_oSRrvUpyPXhpRqflvmzU", "source_state": "uttar_pradesh", "source_name": "ghazipur", "destination_state": "bihar", "destination_name": "patna", "vehicle_type": "4_to_6_axle", "duration": "4 hour 53 mins", "distance": "195.2 km", "toll_plaza_details": [ { "toll_plaza_name": "Kulhariya", "cost": "565", "toll_plaza_longitude": "84.76861", "toll_plaza_latitude": "25.58056" }, { "toll_plaza_name": "Dalsagar", "cost": "525", "toll_plaza_longitude": "84.060688", "toll_plaza_latitude": "25.580548" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Toll Enroute

Toll Enroute API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses