Pincode API Documentation

blog-img
  • Jul 2024, 01:00 AM

Pincode API Documentation

Overview

The Pincode API provides a set of endpoints to retrieve information about pincodes, states, districts, and tehsils in India. This API is useful for applications that require location-based data.

 

Base URL

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 (Using Only Pincode)

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): The pincode to fetch information for.

 

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": "Kokodi",

            "branchType": "BO",

            "deliveryStatus": "Delivery",

            "districtName": "GONDIA",

            "stateName": "MAHARASHTRA"

        },

        {

            "postalCircle": "Maharashtra Circle",

            "postalCode": 441901,

            "postalRegion": "Nagpur Region",

            "postalDivision": "Nagpur Moffusil Division",

            "postOfficeName": "Murdoli",

            "branchType": "BO",

            "deliveryStatus": "Delivery",

            "districtName": "GONDIA",

            "stateName": "MAHARASHTRA"

        },

        {

            "postalCircle": "Maharashtra Circle",

            "postalCode": 441901,

            "postalRegion": "Nagpur Region",

            "postalDivision": "Nagpur Moffusil Division",

            "postOfficeName": "Shirpurbagh Colony",

            "branchType": "BO",

            "deliveryStatus": "Delivery",

            "districtName": "GONDIA",

            "stateName": "MAHARASHTRA"

        },

        {

            "postalCircle": "Maharashtra Circle",

            "postalCode": 441901,

            "postalRegion": "Nagpur Region",

            "postalDivision": "Nagpur Moffusil Division",

            "postOfficeName": "Alewada",

            "branchType": "BO",

            "deliveryStatus": "Delivery",

            "districtName": "GONDIA",

            "stateName": "MAHARASHTRA"

        },

        {

            "postalCircle": "Maharashtra Circle",

            "postalCode": 441901,

            "postalRegion": "Nagpur Region",

            "postalDivision": "Nagpur Moffusil Division",

            "postOfficeName": "Chichgarh",

            "branchType": "BO",

            "deliveryStatus": "Delivery",

            "districtName": "GONDIA",

            "stateName": "MAHARASHTRA"

        },

        {

            "postalCircle": "Maharashtra Circle",

            "postalCode": 441901,

            "postalRegion": "Nagpur Region",

            "postalDivision": "Nagpur Moffusil Division",

            "postOfficeName": "Futana",

            "branchType": "BO",

            "deliveryStatus": "Delivery",

            "districtName": "GONDIA",

            "stateName": "MAHARASHTRA"

        },

        {

            "postalCircle": "Maharashtra Circle",

            "postalCode": 441901,

            "postalRegion": "Nagpur Region",

            "postalDivision": "Nagpur Moffusil Division",

            "postOfficeName": "Borgaon",

            "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): Partial or full name of the state to search for. Supports autocompletion.

 

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 within a specified state (state id, that retrived in the endpoint "/pincodes/district/{state_id}/{district_name}").

  • Endpoint: pincodes/district/{state_ID}/{district_name}
  • Method: GET
  • Parameters:
    • state_ID (integer, required): ID of the state.
    • district_name (string, required): Partial or full name of the district to search for. Supports autocompletion.

 

Request Example (As per our database record, "1" is the state id of "Andhra Pradesh" state):

GET /pincodes/district/1/ben

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 (it includes State name, District name, Tehsil name)

Retrieve post office details with a specific post office name.

 

Why here we requires state_name, district_name and tehsil_name along with post_office_name?

There are many post offices with same name, to avoid conflict between two post office name we requires  state_name, district_name and tehsil_name alongwith 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.0: Initial release with basic pincode, state, district, and tehsil information.

Support and Contact Information

For support, please contact our team at [email protected] or visit our support page.

 

Live Demo

Github (Javascript) -> https://github.com/Nandeshwar750/india-pincode-api-demo

Live (With PHP backend) -> https://mostlyusedtools.com/tool/post-office-search-by-name 

 

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.

 

FAQs - Frequently Asked Questions

The Pincode API provides endpoints to retrieve information about pincodes, states, districts, and tehsils in India, useful for location-based data applications.

The base URL is https://pincodes.nskmultiservices.in/api

Use an API key included in the request header as Authorization: Bearer YOUR_API_KEY

Register on our platform to receive an API key.

Premium users can make 120 requests per minute, while regular users are limited to 60 requests per minute.

You will receive an HTTP 429 error indicating "Too many requests."

Use the endpoint /pincode/{pincode_number} with the method GET.

The response includes postal circle, postal code, postal region, postal division, post office name, branch type, delivery status, district name, and state name.

Use the endpoint /pincodes/details/{state_name}/{district_name}/{post_office_name} with the method GET.

Example request: GET /pincodes/details/maharashtra/gondia/Dongargaon with Authorization: Bearer YOUR_API_KEY.

The response includes postal circle, postal code, postal region, postal division, post office name, branch type, delivery status, district name, state name, and location coordinates.

Search Pincode by Post Office Name OR Pincode

OR

Menus

Area wise pincodes Pincode of your Current Location Download Pincodes Details (PDF/Excel)

Click following link to submit your Feedback: Feedback Form