Get Toll Plaza Names by State

Endpoint Overview

POST /api/v1/nhai/get-toll-plaza-name

Description

The NHAI Toll Plaza Names API retrieves a comprehensive list of toll plaza names within a specified Indian state. This endpoint serves as a crucial component in the toll calculation workflow, providing detailed toll plaza information that enables precise route planning and cost estimation. By supplying a specific state identifier, users can access all operational toll plazas managed by the National Highway Authority of India (NHAI) within that geographical region.

This API is essential for applications requiring granular toll plaza data for route optimization, toll cost calculations, and transportation planning. It bridges the gap between state-level toll information and specific toll plaza details, enabling developers to build sophisticated logistics and travel planning solutions with precise toll plaza identification.

Key Benefits

State-Specific Filtering: Get targeted toll plaza information for precise geographical planning

Complete Plaza Coverage: Access all operational toll plazas within the specified state

Enhanced Route Planning: Enable detailed route optimization with specific toll plaza data

Unique Client Tracking: Receive client-specific identifiers for transaction tracking and audit trails

Use Cases

Logistics & Fleet Management

Travel & Navigation

Financial & Business Services

Route Optimization Systems: Identify specific toll plazas along planned routes for accurate cost and time estimation

Fleet Tracking Applications: Monitor vehicle progress through state-specific toll checkpoints

Freight Cost Calculation: Determine exact toll expenses for shipments crossing specific state boundaries

Supply Chain Planning: Optimize delivery routes by analyzing toll plaza density and locations within states

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 format)
Content-Type	Yes	Must be set to application/json

Request Body

Parameter	Type	Required	Description
state_name	String	Yes	The state identifier for which toll plaza names are requested. Must match the standardized state naming convention (e.g., "uttarakhand", "maharashtra")

Example Request

{
    "state_name": "uttarakhand"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object holding the response data
data.client_id	String	Unique client identifier for tracking and audit purposes
data.state_name	String	Echoed state name from the request for confirmation
data.toll_plaza_list	Array[String]	List of toll plaza names within the specified state
status_code	Number	HTTP status code indicating request success/failure
success	Boolean	Flag indicating overall request success status
message	String	Human-readable response message (null on success)
message_code	String	Internal status code for programmatic handling

Example Successful Response

{
    "data": {
        "client_id": "toll_plaza_name_bCIgBXcCmHfDctzAfOxu",
        "state_name": "uttarakhand",
        "toll_plaza_list": [
            "Bahadrabad",
            "Bhagwanpur",
            "Chhapar",
            "Jagatpur Patti",
            "Koyla",
            "Lacchiwala",
            "Puraini",
            "Sarsawa",
            "Sayed Majra"
        ]
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid State

Authentication Error

Missing Parameters

{
    "errors": {
        "source_state": "source_state The value 'uttar_prade' is not a valid choice for 'source_state'."
    },
    "message": "Input payload validation failed"
}

Occurs when the provided state name doesn't match any available states or uses incorrect formatting. Verify the state name against the standardized list.

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely and implement automatic token refresh mechanisms

HTTPS Only: Always use HTTPS for API communications to protect authentication credentials and sensitive data

Input Validation: Validate state names on the client side before sending requests to reduce unnecessary API calls

Rate Limiting: Implement client-side rate limiting to avoid overwhelming the API endpoints

User Experience Guidelines

Caching Strategy: Cache toll plaza lists per state as they change infrequently, improving performance and reducing API calls

Autocomplete Features: Use the toll plaza names for search autocomplete and suggestion features

Error Handling: Provide clear error messages to users when invalid state names are entered

Loading States: Display appropriate loading indicators while fetching toll plaza information

Code Samples

cURL

Python

Node.js

Related APIs

Get Toll Plaza States: Retrieve the list of all available states with toll plazas for initial selection

Calculate Toll Charges: Compute toll costs for specific routes using toll plaza information

Get Toll Plaza Details: Access detailed information about specific toll plazas including rates and facilities

Route Optimization: Advanced routing APIs that incorporate toll plaza data for cost-effective path planning

Compliance and Legal Considerations

This API provides data related to official NHAI toll plazas and should be used in compliance with Indian transportation regulations. The toll plaza names returned are official designations and should be used accurately in any toll-related applications. Users should ensure that any toll calculation or route planning applications comply with current NHAI policies and guidelines. The client_id provided in responses should be stored for audit trails and transaction tracking as required by regulatory compliance.

{ "data": { "client_id": "toll_plaza_name_bCIgBXcCmHfDctzAfOxu", "state_name": "uttarakhand", "toll_plaza_list": [ "Bahadrabad", "Bhagwanpur", "Chhapar", "Jagatpur Patti", "Koyla", "Lacchiwala", "Puraini", "Sarsawa", "Sayed Majra" ] }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Get Toll Plaza Name

Get Toll Plaza Names by State#

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