Get Toll Plaza States

Endpoint Overview

GET /api/v1/nhai/get-toll-plaza-states

Description

The NHAI Toll Plaza States API provides a comprehensive list of Indian states where toll plazas are operational under the National Highway Authority of India (NHAI). This foundational endpoint serves as a prerequisite for accessing detailed toll pricing information across the Indian highway network. The API returns standardized state identifiers that are essential for subsequent toll-related queries, ensuring accurate and region-specific toll calculations for transportation and logistics applications.

This endpoint streamlines the process of toll cost estimation by providing the exact state nomenclature required for further API interactions, eliminating guesswork and ensuring consistent data retrieval across the NHAI toll system.

Key Benefits

Standardized State Identifiers: Provides consistent state naming conventions for reliable API interactions

Complete Coverage: Includes all states with active NHAI toll plazas for comprehensive route planning

Foundation for Toll Queries: Essential prerequisite data for accurate toll cost calculations

Real-time Availability: Returns current list of states with operational toll infrastructure

Use Cases

Logistics & Transportation

Travel & Tourism

Financial Services

Fleet Management Systems: Initialize route planning modules with available toll states for accurate cost estimation

Freight Booking Platforms: Validate origin and destination states before calculating toll charges for shipments

Last-Mile Delivery: Optimize delivery routes by identifying toll-applicable states in the logistics network

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

This endpoint does not require any request body parameters. It's a simple GET request that returns all available toll plaza states.

Example Request

// No request body required for this endpoint

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object holding the response data
data.state_name	Array[String]	List of state identifiers with active toll plazas
status_code	Number	HTTP status code indicating request success/failure
message_code	String	Internal status code for programmatic handling
message	String	Human-readable response message
success	Boolean	Flag indicating overall request success status

Example Successful Response

{
    "data": {
        "state_name": [
            "andhra_pradesh",
            "assam",
            "bihar",
            "chhattisgarh",
            "delhi",
            "gujarat",
            "himachal_pradesh",
            "jammu_and_kashmir",
            "jharkhand",
            "karnataka",
            "kerala",
            "madhya_pradesh",
            "maharashtra",
            "meghalaya",
            "odisha",
            "punjab_and_haryana",
            "rajasthan",
            "tamil_nadu",
            "telangana",
            "uttar_pradesh",
            "uttarakhand",
            "west_bengal"
        ]
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Authentication Error

Server Error

{
    "status_code": 401,
    "message_code": "unauthorized",
    "message": "Invalid or expired authentication token",
    "success": false
}

Occurs when the JWT token is missing, invalid, or expired. Verify your authentication credentials and token generation process.

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

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

Error Handling: Implement comprehensive error handling for authentication and network failures

User Experience Guidelines

Caching Strategy: Cache the state list locally as it changes infrequently, reducing API calls and improving performance

Fallback Mechanisms: Implement fallback options when API is temporarily unavailable

User-Friendly Names: Map technical state identifiers to human-readable names for better user experience

Loading States: Show appropriate loading indicators while fetching state information

Code Samples

cURL

Python

Node.js

Related APIs

Get Toll Plaza Details: Retrieve detailed information about toll plazas within specific states

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

Get Highway Information: Access comprehensive highway data including toll plaza locations

Route Optimization: Advanced routing APIs that incorporate toll cost calculations

Compliance and Legal Considerations

This API provides data related to official NHAI toll plazas and should be used in compliance with Indian transportation regulations. Users should ensure that any toll-related calculations or route planning applications comply with current NHAI policies and guidelines. The state identifiers returned are standardized for API consistency and may not reflect official administrative naming conventions.

{ "data": { "state_name": [ "andhra_pradesh", "assam", "bihar", "chhattisgarh", "delhi", "gujarat", "himachal_pradesh", "jammu_and_kashmir", "jharkhand", "karnataka", "kerala", "madhya_pradesh", "maharashtra", "meghalaya", "odisha", "punjab_and_haryana", "rajasthan", "tamil_nadu", "telangana", "uttar_pradesh", "uttarakhand", "west_bengal" ] }, "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Get Toll Plaza States

Get Toll Plaza States#

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

Get Toll Plaza States

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples