State List

Endpoint Overview

GET /api/v1/utilities/fuel-price/state-list

Description

This endpoint retrieves a comprehensive list of all Indian states and union territories for which fuel price data is available through the Surepass API. The endpoint returns state names in a standardized format (snake_case) that can be used in subsequent fuel price lookup requests. This allows developers to build applications that display or analyze fuel prices across different regions of India without hardcoding state values.

Key Benefits

Provides a complete, up-to-date list of all supported states and union territories

Returns standardized state name formats required for subsequent fuel price API calls

Simplifies application development by eliminating the need to maintain state lists locally

Ensures applications always have access to the most current coverage area

Use Cases

Logistics & Transportation

Consumer Applications

Data Analytics

Build fuel cost calculators for route planning across multiple states

Develop logistics applications that factor in regional fuel price variations

Create dashboards for fleet managers to monitor fuel expenses by region

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	JWT Bearer token for authentication. Format: `Bearer <your_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

This endpoint does not require any parameters in the request body.

Example Request

No request body required

Process Response

Response Parameters

Parameter	Type	Description
state	array	An array of strings representing the names of states and union territories in snake_case format

Example Successful Response

{
    "state": [
        "andaman_and_nicobar",
        "andhra_pradesh",
        "arunachal_pradesh",
        "assam",
        "bihar",
        "chandigarh",
        "chhattisgarh",
        "dadra_and_nagar_haveli",
        "daman_and_diu",
        "delhi",
        "goa",
        "gujarat",
        "haryana",
        "himachal_pradesh",
        "jammu_and_kashmir",
        "jharkhand",
        "karnataka",
        "kerala",
        "madhya_pradesh",
        "maharashtra",
        "manipur",
        "meghalaya",
        "mizoram",
        "nagaland",
        "odisha",
        "puducherry",
        "punjab",
        "rajasthan",
        "sikkim",
        "tamilnadu",
        "telangana",
        "tripura",
        "uttar_pradesh",
        "uttarakhand",
        "west_bengal"
    ]
}

Possible Error Responses

Authentication Error

Server Error

{
    "error": null,
    "message": "Your token is invalid. Please ensure that correct token is being used.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

This error occurs when the JWT token is missing, invalid, or expired. Ensure you're using the correct token for the environment.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data security

Implement proper error handling for authentication failures

User Experience Guidelines

Cache the state list to reduce API calls and improve application performance

Implement a fallback mechanism if the API is temporarily unavailable

Convert snake_case state names to proper case for display to end-users

Provide clear feedback to users when fuel price data is being fetched

Code Samples

cURL

Python

Node.js

Related APIs

Fuel Price by State: Retrieves current fuel prices for a specific state

Fuel Price History: Provides historical fuel price data for analysis

City List by State: Returns a list of cities within a state for which fuel prices are available

Compliance and Legal Considerations

The fuel price data provided through this API is sourced from official government channels. While the API provides access to this data, applications should clearly indicate the source and timestamp of fuel prices to users. The data should not be represented as real-time unless explicitly stated in the documentation for the specific fuel price endpoints.

{ "state": [ "andaman_and_nicobar", "andhra_pradesh", "arunachal_pradesh", "assam", "bihar", "chandigarh", "chhattisgarh", "dadra_and_nagar_haveli", "daman_and_diu", "delhi", "goa", "gujarat", "haryana", "himachal_pradesh", "jammu_and_kashmir", "jharkhand", "karnataka", "kerala", "madhya_pradesh", "maharashtra", "manipur", "meghalaya", "mizoram", "nagaland", "odisha", "puducherry", "punjab", "rajasthan", "sikkim", "tamilnadu", "telangana", "tripura", "uttar_pradesh", "uttarakhand", "west_bengal" ] }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

State List

State List#

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

State List

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples