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.

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:

HTTP Request 
GET /pincode/441901
Authorization: Bearer YOUR_API_KEY

Response (in JSON Format):

JSON Response 
{
    "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:

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

Response Example:

JSON Response
[
  "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:

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

Response Example:

JSON Response 
{
"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"
    }
}
}

Digipin API Endpoints

1. Generate Digipin

Generate a DIGIPIN from latitude and longitude coordinates.

Endpoint:
POST /api/digipin/generate
Method:
POST

Request Body:

  • latitude (float, required): Latitude value.
  • longitude (float, required): Longitude value.

Request Example:

HTTP Request
POST /api/digipin/generate
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "latitude": 19.123456,
  "longitude": 73.987654
}

Response Example:

JSON Response
{
  "success": true,
  "data": {
    "digipin": "A1B2C3D4",
    "latitude": 19.123456,
    "longitude": 73.987654
  }
}

Error Response:

{
  "success": false,
  "message": "Error message here."
}

2. Decode Digipin

Decode a DIGIPIN to retrieve latitude and longitude coordinates.

Endpoint:
POST /api/digipin/decode
Method:
POST

Request Body:

  • digipin (string, required): The DIGIPIN code to decode.

Request Example:

HTTP Request
POST /api/digipin/decode
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "digipin": "A1B2C3D4"
}

Response Example:

JSON Response
{
  "success": true,
  "data": {
    "digipin": "A1B2C3D4",
    "latitude": 19.123456,
    "longitude": 73.987654
  }
}

Error Response:

{
  "success": false,
  "message": "Invalid DIGIPIN format"
}

3. Get Digipin Info

Retrieve information and configuration details about the DIGIPIN system.

Endpoint:
GET /api/digipin/info
Method:
GET

Response Example:

JSON Response
{
  "success": true,
  "data": {
    "description": "DIGIPIN is a geocoding system for encoding latitude and longitude into a short code.",
    "bounds": {
      "minLatitude": -90,
      "maxLatitude": 90,
      "minLongitude": -180,
      "maxLongitude": 180
    },
    "grid": "1km x 1km",
    "validCharacters": "ABCDEFGHJKLMNPQRSTUVWXYZ23456789",
    "endpoints": {
      "generate": "/api/digipin/generate",
      "decode": "/api/digipin/decode",
      "info": "/api/digipin/info"
    }
  }
}

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.

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.