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.

We use cookies to enhance your browsing experience and analyze our traffic. By clicking "Accept", you consent to our use of cookies. Read our Privacy Policy and Cookie Policy to learn more.