Pincode API Documentation

The Pincode API provides a comprehensive set of endpoints to retrieve information about pincodes, states, districts, and tehsils in India. This API is designed for applications that require accurate and up-to-date location-based data for Indian postal addresses.

Base URL

API Endpoint
https://pincodes.nskmultiservices.in/api

Authentication

API Key: This API requires an API key for access. You can obtain an API key by registering on our platform.

Authentication Method: Include the API key in the request header as:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

Premium Users: 120 requests per minute.

Regular Users: 60 requests per minute.

Error Response: HTTP 429 - Too many requests.

Endpoints

1. Get Pincode Information

Retrieve details about a specific pincode. Standalone API endpoint to retrieve pincode details of a specific pincode number.

Endpoint:
/pincode/{pincode_number}
Method:
GET
Parameters:
pincode (string, required)

Request: 

GET /pincode/441901
Authorization: Bearer YOUR_API_KEY

Response (in JSON Format):

{
    "status": "success",
    "data": [
        {
        "postalCircle": "Maharashtra Circle",
        "postalCode": 441901,
        "postalRegion": "Nagpur Region",
        "postalDivision": "Nagpur Moffusil Division",
        "postOfficeName": "Dawki",
        "branchType": "BO",
        "deliveryStatus": "Delivery",
        "districtName": "GONDIA",
        "stateName": "MAHARASHTRA"
        },
        {
        "postalCircle": "Maharashtra Circle",
        "postalCode": 441901,
        "postalRegion": "Nagpur Region",
        "postalDivision": "Nagpur Moffusil Division",
        "postOfficeName": "Kadikasa",
        "branchType": "BO",
        "deliveryStatus": "Delivery",
        "districtName": "GONDIA",
        "stateName": "MAHARASHTRA"
        },
        {
        "postalCircle": "Maharashtra Circle",
        "postalCode": 441901,
        "postalRegion": "Nagpur Region",
        "postalDivision": "Nagpur Moffusil Division",
        "postOfficeName": "Nilaj",
        "branchType": "BO",
        "deliveryStatus": "Delivery",
        "districtName": "GONDIA",
        "stateName": "MAHARASHTRA"
        },
        {
        "postalCircle": "Maharashtra Circle",
        "postalCode": 441901,
        "postalRegion": "Nagpur Region",
        "postalDivision": "Nagpur Moffusil Division",
        "postOfficeName": "Deori(Gondia)",
        "branchType": "PO",
        "deliveryStatus": "Delivery",
        "districtName": "GONDIA",
        "stateName": "MAHARASHTRA"
        }
    ]
}

Error Codes:

404 Not Found: Pincode not found.

429 Too Many Requests: Rate limit exceeded.

2. Get State Names

Retrieve a list of states matching the provided state name.

Endpoint:
/state/{stateName}
Method:
GET
Parameters:
stateName (string, required)

Request Example:

GET /pincodes/state/pradesh
Authorization: Bearer YOUR_API_KEY

Response (in JSON Format):

[
    {
        "id": 1,
        "name": "Andhra Pradesh"
    },
    {
        "id": 2,
        "name": "Arunachal Pradesh"
    },
    {
        "id": 13,
        "name": "Himachal Pradesh"
    },
    {
        "id": 19,
        "name": "Madhya Pradesh"
    },
    {
        "id": 34,
        "name": "Uttar Pradesh"
    }
]

Error Codes:

404 Not Found: State not found.

3. Get District Names

Retrieve a list of districts matching the provided district name.

Endpoint:
/district/{districtName}
Method:
GET
Parameters:
districtName (string, required)

Request Example:

GET /pincodes/district/gondia
Authorization: Bearer YOUR_API_KEY

Response Example:

[
    "Bengaluru Rural",
    "Bengaluru Urban"
]

4. Get Tehsil Names

Retrieve a list of tehsils matching the provided state, district, and tehsil names.

Endpoint:
/pincodes/tehsil/{state_name}/{district_name}/{tehsil_name}
Method:
GET

Parameters:

  • state_name (string, required): The name of the state.
  • district_name (string, required): The name of the district.
  • tehsil_name (string, required): Partial or full name of the tehsil.

Request Example:

GET /pincodes/tehsil/maharashtra/gondia/gaon
Authorization: Bearer YOUR_API_KEY

Response Example:

[
    "Amgaon",
    "Arjuni Morgaon",
    "Goregaon(Gondia)",
    "Navegaon Bandh"
]

5. Get Pincodes by using Post Office Name

Retrieve post office details with a specific post office name. (Includes State name, District name, Tehsil name)

Why do we require state_name, district_name and tehsil_name along with post_office_name?

There are many post offices with the same name. To avoid conflicts between two post office names, we require state_name, district_name and tehsil_name along with post_office_name to retrieve accurate data.

After getting State name, District and Tehsil name (using autocomplete functionality), you can easily get Post office details by post office name.

Endpoint:
/pincodes/details/{state_name}/{district_name}/{post_office_name}
Method:
GET

Parameters:

  • state_name (string, required): The name of the state.
  • district_name (string, required): The name of the district.
  • post_office_name (string, required): Full name of the post office (Exact match NOT partial match).

Request Example:

GET /pincodes/details/maharashtra/gondia/Dongargaon
Authorization: Bearer YOUR_API_KEY

Response Example:

{
    "status": "success",
    "data": {
        "postalCircle": "Maharashtra Circle",
        "postalCode": 441614,
        "postalRegion": "Nagpur Region",
        "postalDivision": "Nagpur Moffusil Division",
        "postOfficeName": "Dongargaon",
        "branchType": "BO",
        "deliveryStatus": "Delivery",
        "districtName": "GONDIA",
        "stateName": "MAHARASHTRA",
        "location": {
            "latitude": "21.3678710",
            "longitude": "79.9933980"
        }
    }
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Common error codes include:

  • 400 Bad Request: The request was malformed or invalid.
  • 401 Unauthorized: The request lacked proper authentication.
  • 403 Forbidden: The user does not have permission to access the resource.
  • 404 Not Found: The requested resource was not found.
  • 429 Too Many Requests: The rate limit was exceeded.
  • 500 Internal Server Error: An unexpected error occurred on the server.

Changelog

v1.1.0 - March 2024

  • Added location coordinates (latitude/longitude) to post office details
  • Improved search accuracy for post office names
  • Enhanced rate limiting system

v1.0.1 - January 2024

  • Fixed district name autocomplete functionality
  • Added support for special characters in post office names
  • Performance optimization for large data queries

v1.0.0 - December 2023

  • Initial release with basic pincode, state, district, and tehsil information
  • Implemented RESTful API endpoints
  • Added authentication system
  • Introduced rate limiting

Support and Contact Information

For support, please contact our team at letstalk@nskmultiservices.in or visit our support page.

Live Demo

Postman Test Collection

Test API Endpoints with Postman

Download our pre-configured Postman collection to quickly test all API endpoints with example requests.

pincodes-api.postman_collection.json
Download Collection

✓ Contains all API endpoints

✓ Includes example requests and responses

✓ Environment variables pre-configured

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Common error codes include:

  • 400 Bad Request: The request was malformed or invalid.
  • 401 Unauthorized: The request lacked proper authentication.
  • 403 Forbidden: The user does not have permission to access the resource.
  • 404 Not Found: The requested resource was not found.
  • 429 Too Many Requests: The rate limit was exceeded.
  • 500 Internal Server Error: An unexpected error occurred on the server.

Changelog

  • v1.0: Initial release with basic pincode, state, district, and tehsil information.

Support and Contact Information

You can test the API using Postman. Here's a sample collection: Download Postman Collection

Best Practices and Security

  • Use HTTPS for secure communication.
  • Do not expose your API key in client-side code.
  • Handle errors gracefully and provide meaningful messages to the end user.