Pincode API — V1

A comprehensive REST API for India Post data: pincode lookups, post office search, nearby post offices by coordinates, village-to-pincode mapping, state/district browsing, and full DIGIPIN encode/decode support.

Public endpoints — no auth required JSON responses Rate limited

Base URL

https://yourdomain.com/api/v1

All endpoint paths in this document are relative to this base URL.

Authentication

All Pincode and DIGIPIN endpoints are public. No API key or Authorization header is required.

Other API modules (AI, user profile, plugins) require a Bearer token obtained from POST /api/v1/login.

Rate Limiting

Public endpoints share the default rate limit tier. Exceeding the limit returns 429 Too Many Requests.

Tier	Limit
Public (pincode/digipin)	Default — configured in `api.rate.limit`
Auth endpoints (login/register)	Stricter auth tier

Pincode Endpoints

GET

1. Lookup by Pincode

Returns all post offices that share a 6-digit pincode.

GET /pincodes/{pincode}

Request

GET /api/v1/pincodes/110001

Response 200

JSON

{
  "success": true,
  "data": {
    "pincode": "110001",
    "total": 3,
    "post_offices": [
      {
        "id": 1,
        "pincode": "110001",
        "post_office": "Connaught Place HO",
        "branch_type": "HO",
        "delivery_status": "Delivery",
        "circle": "Delhi",
        "region": "Delhi",
        "division": "Delhi Central",
        "district": "Central Delhi",
        "state": "Delhi",
        "location": {
          "latitude": 28.6315,
          "longitude": 77.2167
        },
        "reviews_count": 4,
        "likes_count": 12
      }
    ]
  }
}

404 — Pincode not found.

422 — Pincode is not exactly 6 digits.

GET

2. Post Office Details

Returns full details for a specific post office within a pincode. Use the optional ?post_office= query param to disambiguate when multiple offices share the same pincode.

GET /pincodes/{pincode}/details?post_office={name}

Request

GET /api/v1/pincodes/110001/details
GET /api/v1/pincodes/110001/details?post_office=Connaught+Place+HO

Response 200

JSON

{
  "success": true,
  "data": {
    "id": 1,
    "pincode": "110001",
    "post_office": "Connaught Place HO",
    "branch_type": "HO",
    "delivery_status": "Delivery",
    "circle": "Delhi",
    "region": "Delhi",
    "division": "Delhi Central",
    "district": "Central Delhi",
    "state": "Delhi",
    "location": {
      "latitude": 28.6315,
      "longitude": 77.2167
    },
    "reviews_count": 4,
    "likes_count": 12
  }
}

GET

3. Search

Full-text search across post office name, district, state, and pincode prefix. Numeric queries match pincode prefix; text queries match name/district/state.

GET /pincodes/search?q={term}&state={state}&district={district}&per_page={n}

Query Parameters

Param	Required	Notes
q	Yes	Min 2 chars, max 100
state	No	Filter by state name prefix
district	No	Filter by district name prefix
per_page	No	1–100, default 15

Example request

GET /api/v1/pincodes/search?q=Connaught&state=Delhi&per_page=5

GET

4. Nearby Post Offices New

Returns post offices within a given radius (km) of the supplied coordinates, sorted by distance. Falls back to the closest limit offices when no results fall within the radius.

GET /pincodes/nearby?latitude={lat}&longitude={lon}&radius={km}&limit={n}

Query Parameters

Param	Required	Notes
latitude	Yes	-90 to 90
longitude	Yes	-180 to 180
radius	No	km, 0.1–100, default 10
limit	No	1–50, default 5

Request

GET /api/v1/pincodes/nearby?latitude=28.6139&longitude=77.2090&radius=5&limit=3

Response 200

JSON

{
  "success": true,
  "data": {
    "latitude": 28.6139,
    "longitude": 77.209,
    "radius_km": 5,
    "post_offices": [
      {
        "pincode": "110001",
        "post_office": "Connaught Place HO",
        "district": "Central Delhi",
        "state": "Delhi",
        "location": { "latitude": 28.6315, "longitude": 77.2167 },
        "distance_km": 1.97
      }
    ]
  }
}

GET

5. Villages by Pincode

Returns paginated villages mapped to a given pincode.

GET /pincodes/{pincode}/villages?per_page={n}

Response 200

{
  "success": true,
  "data": {
    "pincode": "110001",
    "villages": [
      {
        "village_code": "V123456",
        "village_name": "Paharganj",
        "subdistrict": "Central",
        "district": "Central Delhi",
        "state": "Delhi",
        "pincode": "110001"
      }
    ],
    "meta": { "total": 12, "per_page": 50, "current_page": 1, "last_page": 1 }
  }
}

GET

6. Village Search New

Find villages by name and retrieve their pincode. Useful when a user knows the village name but not the pincode.

GET /villages/search?q={name}&state={state}&district={district}&per_page={n}

Example

GET /api/v1/villages/search?q=Rampur&state=Uttar+Pradesh

// Response 200
{
  "success": true,
  "data": {
    "query": "Rampur",
    "villages": [
      {
        "village_code": "V001234",
        "village_name": "Rampur",
        "subdistrict": "Rampur",
        "district": "Rampur",
        "state": "Uttar Pradesh",
        "pincode": "244901"
      }
    ],
    "meta": { "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 }
  }
}

States & Districts

GET

7. List States

Returns all states with district and pincode counts. Optionally filter by name prefix.

GET /states?q={prefix}

Response 200

{
  "success": true,
  "data": {
    "total": 36,
    "states": [
      { "id": 1, "name": "Andhra Pradesh", "districts_count": 26, "pincodes_count": 1842 }
    ]
  }
}

GET

8. State Detail New

Returns full detail for a single state. Accepts either the state ID or name prefix.

GET /states/{state}

GET /api/v1/states/Maharashtra
GET /api/v1/states/5

GET

9. Districts by State

Returns all districts for a state. Accepts state ID or name prefix. Optionally filter districts by name prefix.

GET /states/{state}/districts?q={prefix}

Response 200

{
  "success": true,
  "data": {
    "state": "Maharashtra",
    "total": 36,
    "districts": [
      { "id": 12, "name": "Pune", "alt_name": "Poona", "state_id": 5, "pincodes_count": 312 }
    ]
  }
}

GET

10. District Detail New

Returns full detail for a single district including its parent state. Accepts district ID or name prefix.

GET /districts/{district}

GET /api/v1/districts/Pune
GET /api/v1/districts/12

GET

11. Pincodes by District

Returns paginated post offices for a district. Accepts district ID or name prefix.

GET /districts/{district}/pincodes?per_page={n}

Response 200

{
  "success": true,
  "data": {
    "district": "Pune",
    "state": "Maharashtra",
    "total": 312,
    "results": [ { "pincode": "411001", "post_office": "Pune HO", ... } ],
    "meta": { "total": 312, "per_page": 20, "current_page": 1, "last_page": 16 }
  }
}

DIGIPIN Endpoints

DIGIPIN is India Post's 10-character alphanumeric geocode. These endpoints are public — no API key is required.

POST

Encode — Coordinates → DIGIPIN

Converts a latitude/longitude pair into a 10-character DIGIPIN code.

Endpoint

POST /api/v1/digipin/encode

Auth

Not required

Body

JSON

Request Body Parameters

Parameter	Type	Required	Constraints
latitude	float	Yes	2.5 – 38.5
longitude	float	Yes	63.5 – 99.5

Request

HTTP

POST /api/v1/digipin/encode
Content-Type: application/json

{
  "latitude": 28.6139,
  "longitude": 77.2090
}

Response 200 OK

JSON

{
  "success": true,
  "data": {
    "digipin": "39J-3M2-7K4P",
    "latitude": 28.6139,
    "longitude": 77.209
  }
}

POST

Decode — DIGIPIN → Coordinates

Converts a DIGIPIN code back to its central latitude/longitude. Hyphens are optional.

Request

HTTP

POST /api/v1/digipin/decode
Content-Type: application/json

{
  "digipin": "39J-3M2-7K4P"
}

Response 200 OK

JSON

{
  "success": true,
  "data": {
    "digipin": "39J-3M2-7K4P",
    "latitude": 28.6152,
    "longitude": 77.2104
  }
}

422 Unprocessable: Returned when the DIGIPIN contains invalid characters or is not exactly 10 characters (excluding hyphens).

GET

Validate — Format Check

Checks whether a DIGIPIN string is syntactically valid without performing a full decode. Useful for client-side pre-validation.

Endpoint

GET /api/v1/digipin/validate?digipin={code}

Request

HTTP

GET /api/v1/digipin/validate?digipin=39J3M27K4P

Response 200 OK

JSON

{
  "success": true,
  "data": {
    "digipin": "39J3M27K4P",
    "valid": true,
    "reason": null
  }
}

// Invalid example:
{
  "success": true,
  "data": {
    "digipin": "AAAAAAAAAA",
    "valid": false,
    "reason": "Invalid character(s): A. Valid set: FC98J327K456LMPT."
  }
}

GET

Nearest Post Office

Encodes the given coordinates into a DIGIPIN, then returns the nearest post office(s) by matching boundary geometry. Falls back to Haversine distance if no boundary data exists.

Endpoint

GET /api/v1/digipin/nearest?latitude={lat}&longitude={lon}&limit={n}

Query Parameters

Parameter	Type	Required	Notes
latitude	float	Yes	2.5 – 38.5
longitude	float	Yes	63.5 – 99.5
limit	integer	No	1–10, default 3

Request

HTTP

GET /api/v1/digipin/nearest?latitude=28.6139&longitude=77.2090&limit=2

Response 200 OK

JSON

{
  "success": true,
  "data": {
    "digipin": "39J-3M2-7K4P",
    "latitude": 28.6139,
    "longitude": 77.209,
    "post_offices": [
      {
        "pincode": "110001",
        "post_office": "Connaught Place HO",
        "district": "Central Delhi",
        "state": "Delhi",
        "delivery_status": "Delivery",
        "location": {
          "latitude": 28.6315,
          "longitude": 77.2167
        }
      }
    ]
  }
}

GET

Spec Info

Returns the DIGIPIN specification: geographic bounds, 4×4 grid layout, valid character set, and available endpoint URLs.

Request

HTTP

GET /api/v1/digipin/info

Response 200 OK

JSON

{
  "success": true,
  "data": {
    "description": "India Post geocode — 10 chars, hyphens optional",
    "bounds": {
      "min_latitude": 2.5,
      "max_latitude": 38.5,
      "min_longitude": 63.5,
      "max_longitude": 99.5
    },
    "grid": [["F","C","9","8"],["J","3","2","7"],["K","4","5","6"],["L","M","P","T"]],
    "valid_characters": ["F","C","9","8","J","3","2","7","K","4","5","6","L","M","P","T"],
    "format": "XXXYYY-XXXYYY-XXXX (10 chars, hyphens optional)",
    "endpoints": {
      "encode":   "/api/v1/digipin/encode",
      "decode":   "/api/v1/digipin/decode",
      "info":     "/api/v1/digipin/info",
      "validate": "/api/v1/digipin/validate?digipin=",
      "nearest":  "/api/v1/digipin/nearest?latitude=&longitude="
    }
  }
}

Error Handling

All responses follow a consistent envelope. Errors set "success": false and include a message field. Validation errors also include an errors object.

Error envelope

{
  "success": false,
  "message": "No post offices found for pincode 999999.",
  "errors": { "pincode": ["Pincode must be exactly 6 digits."] }
}

400 Bad Request — malformed request body or missing required field.

404 Not Found — the requested resource does not exist.

422 Unprocessable — validation failed. Check the errors object for field-level details.

429 Too Many Requests — rate limit exceeded. Retry after the Retry-After header value.

500 Internal Server Error — unexpected server-side failure.

Changelog

v1.3.0 — August 2026

All Pincode and DIGIPIN endpoints are now public — no authentication required
New: GET /pincodes/nearby — coordinate-based post office search with Haversine distance
New: GET /villages/search — find villages by name, returns pincode
New: GET /states/{state} — single state detail endpoint
New: GET /districts/{district} — single district detail endpoint
DIGIPIN endpoints corrected to /api/v1/digipin/* with accurate response shapes

v1.2.0 — March 2024

Added DIGIPIN encode, decode, validate, nearest, and info endpoints
Added village-to-pincode mapping endpoint
Added location coordinates to post office responses

v1.0.0 — December 2023

Initial release: pincode lookup, search, states, districts

Documentation

Pincode API — V1

Base URL

Authentication

Rate Limiting

Pincode Endpoints

1. Lookup by Pincode

2. Post Office Details

3. Search

Query Parameters

4. Nearby Post Offices New

Query Parameters

5. Villages by Pincode

6. Village Search New

States & Districts

7. List States

8. State Detail New

9. Districts by State

10. District Detail New

11. Pincodes by District

DIGIPIN Endpoints

Encode — Coordinates → DIGIPIN

Request Body Parameters

Request

Response 200 OK

Decode — DIGIPIN → Coordinates

Request

Response 200 OK

Validate — Format Check

Request

Response 200 OK

Nearest Post Office

Query Parameters

Request

Response 200 OK

Spec Info

Request

Response 200 OK

Error Handling

Changelog

v1.3.0 — August 2026

v1.2.0 — March 2024

v1.0.0 — December 2023

Best Practices

🍪 Cookie Preferences