Fuel Price

Endpoint Overview

POST /api/v1/utilities/fuel-price

Description

This API provides up-to-date fuel prices (petrol and diesel) for all cities within a specified Indian state. It returns comprehensive pricing data organized by city, allowing applications to display current fuel rates across different locations within the selected state.

Key Benefits

Access real-time fuel prices across multiple cities within a state

Easily integrate fuel price information into travel, logistics, or consumer applications

Compare petrol and diesel prices across different cities within the same state

Obtain data in a structured format that's easy to parse and display

Use Cases

Transportation & Logistics

Travel & Tourism

Consumer Applications

Calculate accurate fuel costs for route planning and delivery optimization

Provide drivers with current fuel prices to make informed refueling decisions

Optimize fleet management by identifying cost-effective refueling locations

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

Parameter	Type	Required	Description
state	String	Yes	The name of the Indian state for which fuel prices are requested. State name should be provided in lowercase.

Example Request

{
    "state": "maharashtra"
}

Note: The list of supported states can be obtained using the State List API.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the fuel price information
data.client_id	String	Unique identifier for the client making the request
data.state	String	Name of the state for which fuel prices are provided
data.petrol_price	Object	Object containing petrol prices for each city in the state (city name as key, price as value)
data.diesel_price	Object	Object containing diesel prices for each city in the state (city name as key, price as value)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code representing the response message

Example Successful Response

{
    "data": {
        "client_id": "fuel_price_sruzxOWjjvVHbcTlHjoF",
        "state": "kerala",
        "petrol_price": {
            "alappuzha": "105.82",
            "ernakulam": "105.72",
            "idukki": "107.07",
            "kannur": "105.88",
            "kasaragod": "106.58",
            "kollam": "107.05",
            "kottayam": "106.37",
            "kozhikode": "106.04",
            "malappuram": "106.20",
            "palakkad": "106.62",
            "pathananthitta": "106.46",
            "thiruvananthapuram": "107.46",
            "thrissur": "105.92",
            "wayanad": "106.88"
        },
        "diesel_price": {
            "alappuzha": "94.80",
            "ernakulam": "94.70",
            "idukki": "95.96",
            "kannur": "94.88",
            "kasaragod": "95.53",
            "kollam": "95.95",
            "kottayam": "95.31",
            "kozhikode": "95.02",
            "malappuram": "95.18",
            "palakkad": "95.54",
            "pathananthitta": "95.39",
            "thiruvananthapuram": "96.33",
            "thrissur": "94.89",
            "wayanad": "95.73"
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid State

Authentication Error

Server Error

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

This error occurs when the state name provided is not recognized or is not supported by the API.

Integration Best Practices

Security Recommendations

Store your JWT token securely and never expose it in client-side code

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data is encrypted in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Cache fuel price data for a reasonable period (e.g., a few hours) to reduce API calls

Implement a fallback mechanism if the API is temporarily unavailable

Display the last updated timestamp alongside fuel prices

Format price values appropriately with currency symbols and decimal places

Code Samples

cURL

Python

Node.js

Related APIs

State List API: Provides a list of all supported states for the Fuel Price API

Vehicle Registration Details API: Retrieves vehicle information based on registration number

Driving License Verification API: Verifies driving license details

Compliance and Legal Considerations

The fuel price data is sourced from official government sources and is provided for informational purposes only. Prices may change without notice, and the API data should not be considered as the sole basis for business decisions. Ensure your application displays appropriate disclaimers when showing fuel price information.

{ "data": { "client_id": "fuel_price_sruzxOWjjvVHbcTlHjoF", "state": "kerala", "petrol_price": { "alappuzha": "105.82", "ernakulam": "105.72", "idukki": "107.07", "kannur": "105.88", "kasaragod": "106.58", "kollam": "107.05", "kottayam": "106.37", "kozhikode": "106.04", "malappuram": "106.20", "palakkad": "106.62", "pathananthitta": "106.46", "thiruvananthapuram": "107.46", "thrissur": "105.92", "wayanad": "106.88" }, "diesel_price": { "alappuzha": "94.80", "ernakulam": "94.70", "idukki": "95.96", "kannur": "94.88", "kasaragod": "95.53", "kollam": "95.95", "kottayam": "95.31", "kozhikode": "95.02", "malappuram": "95.18", "palakkad": "95.54", "pathananthitta": "95.39", "thiruvananthapuram": "96.33", "thrissur": "94.89", "wayanad": "95.73" } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Fuel Price

Fuel Price#

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

Fuel Price

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples