# Pincodes API

> Pincode to post office, district and state.

Every post office in the Department of Posts directory, with its district, state, postal division and coordinates.

Base URL `https://api.dharun.dev`. No API key. Answers are JSON, `{ "data": ..., "meta": { ... } }`, and errors are `{ "error": { "code", "message" } }` with a matching HTTP status. Rate limit: 600 requests a minute per client.

## Post offices for a pincode

`GET /v1/pincode/{pincode}`

Returns the district and state of the pincode and every post office that uses it.

Parameters:

- `pincode` (path, required): Six-digit pincode.

Example: https://api.dharun.dev/v1/pincode/637001

Response, with lists and long text shortened:

```json
{
  "data": {
    "pincode": "637001",
    "district": "Namakkal",
    "stateCode": "TN",
    "state": "Tamil Nadu",
    "offices": [
      {
        "name": "Namakkal H.O",
        "type": "Head Office",
        "delivery": true,
        "division": "Namakkal",
        "region": "Western Region, Coimbatore",
        "circle": "Tamilnadu",
        "district": "Namakkal",
        "stateCode": "TN",
        "state": "Tamil Nadu",
        "latitude": 11.2155833,
        "longitude": 78.1702778
      },
      {
        "name": "Namakkal Bazaar S.O",
        "type": "Post Office",
        "delivery": false,
        "division": "Namakkal",
        "region": "Western Region, Coimbatore",
        "circle": "Tamilnadu",
        "district": "Namakkal",
        "stateCode": "TN",
        "state": "Tamil Nadu",
        "latitude": 11.2240556,
        "longitude": 78.1703333
      },
      {
        "name": "Namakkal Fort S.O",
        "type": "Post Office",
        "delivery": false,
        "division": "Namakkal",
        "region": "Western Region, Coimbatore",
        "circle": "Tamilnadu",
        "district": "Namakkal",
        "stateCode": "TN",
        "state": "Tamil Nadu",
        "latitude": 11.238,
        "longitude": 78.166
      }
    ]
  },
  "meta": {
    "source": {
      "name": "All India Pincode Directory",
      "url": "https://www.data.gov.in/resource/all-india-pincode-directory-till-last-month",
      "licence": "Government Open Data License - India (GODL)",
      "version": "23760720 bytes",
      "retrieved": "2026-10-13",
      "attribution": "Contains data from the All India Pincode Directory, Department of Posts, published on data.gov.in under the Government Open Data License - India."
    }
  }
}
```

## Search post offices

`GET /v1/pincode`

Find post offices by the start of their name, by the start of a pincode, or list a district.

Parameters:

- `q` (query): Start of a post office name (2+ characters) or start of a pincode.
- `state` (query): State code or name, for example TN or Tamil Nadu.
- `district` (query): Exact district name.
- `limit` (query): Results per page, 1 to 100.
- `offset` (query): Results to skip.

Example: https://api.dharun.dev/v1/pincode?q=namakkal&state=TN

Response, with lists and long text shortened:

```json
{
  "data": [
    {
      "pincode": "637001",
      "name": "Namakkal Bazaar S.O",
      "type": "Post Office",
      "delivery": false,
      "division": "Namakkal",
      "region": "Western Region, Coimbatore",
      "circle": "Tamilnadu",
      "district": "Namakkal",
      "stateCode": "TN",
      "state": "Tamil Nadu",
      "latitude": 11.2240556,
      "longitude": 78.1703333
    },
    {
      "pincode": "637003",
      "name": "Namakkal District Court Buildings S.O",
      "type": "Post Office",
      "delivery": false,
      "division": "Namakkal",
      "region": "Western Region, Coimbatore",
      "circle": "Tamilnadu",
      "district": "Namakkal",
      "stateCode": "TN",
      "state": "Tamil Nadu",
      "latitude": 11.2497338,
      "longitude": 78.1265014
    },
    {
      "pincode": "637001",
      "name": "Namakkal Fort S.O",
      "type": "Post Office",
      "delivery": false,
      "division": "Namakkal",
      "region": "Western Region, Coimbatore",
      "circle": "Tamilnadu",
      "district": "Namakkal",
      "stateCode": "TN",
      "state": "Tamil Nadu",
      "latitude": 11.238,
      "longitude": 78.166
    }
  ],
  "meta": {
    "total": 4,
    "limit": 20,
    "offset": 0,
    "source": {
      "name": "All India Pincode Directory",
      "url": "https://www.data.gov.in/resource/all-india-pincode-directory-till-last-month",
      "licence": "Government Open Data License - India (GODL)",
      "version": "23760720 bytes",
      "retrieved": "2026-10-13",
      "attribution": "Contains data from the All India Pincode Directory, Department of Posts, published on data.gov.in under the Government Open Data License - India."
    }
  }
}
```

## Post offices near a point

`GET /v1/pincode/near`

Post offices within a radius of a latitude and longitude, nearest first, with the distance. Positions come from the Department of Posts and some are approximate.

Parameters:

- `lat` (query, required): Latitude in decimal degrees.
- `lng` (query, required): Longitude in decimal degrees.
- `radius` (query): Kilometres, 1 to 50. Default 5.
- `limit` (query): Results, 1 to 100. Default 10.

Example: https://api.dharun.dev/v1/pincode/near?lat=11.2189&lng=78.1674&radius=5

Response, with lists and long text shortened:

```json
{
  "data": [
    {
      "pincode": "636142",
      "name": "Mullukurichi S.O",
      "type": "Post Office",
      "delivery": true,
      "division": "Salem East",
      "region": "Western Region, Coimbatore",
      "circle": "Tamilnadu",
      "district": "Namakkal",
      "stateCode": "TN",
      "state": "Tamil Nadu",
      "latitude": 11.2155833,
      "longitude": 78.1702778,
      "distanceKm": 0.48
    },
    {
      "pincode": "637001",
      "name": "Namakkal H.O",
      "type": "Head Office",
      "delivery": true,
      "division": "Namakkal",
      "region": "Western Region, Coimbatore",
      "circle": "Tamilnadu",
      "district": "Namakkal",
      "stateCode": "TN",
      "state": "Tamil Nadu",
      "latitude": 11.2155833,
      "longitude": 78.1702778,
      "distanceKm": 0.48
    },
    {
      "pincode": "637411",
      "name": "Semmedu S.O",
      "type": "Post Office",
      "delivery": true,
      "division": "Namakkal",
      "region": "Western Region, Coimbatore",
      "circle": "Tamilnadu",
      "district": "Namakkal",
      "stateCode": "TN",
      "state": "Tamil Nadu",
      "latitude": 11.2155833,
      "longitude": 78.1702778,
      "distanceKm": 0.48
    }
  ],
  "meta": {
    "total": 20,
    "limit": 10,
    "offset": 0,
    "source": {
      "name": "All India Pincode Directory",
      "url": "https://www.data.gov.in/resource/all-india-pincode-directory-till-last-month",
      "licence": "Government Open Data License - India (GODL)",
      "version": "23760720 bytes",
      "retrieved": "2026-10-13",
      "attribution": "Contains data from the All India Pincode Directory, Department of Posts, published on data.gov.in under the Government Open Data License - India."
    },
    "note": "Positions come from the Department of Posts directory, where about one office in ten has none and some are approximate. The nearest office is not always the one…"
  }
}
```

## Data source

- [All India Pincode Directory](https://www.data.gov.in/resource/all-india-pincode-directory-till-last-month), 23760720 bytes, retrieved 2026-10-13. Licence: Government Open Data License - India (GODL). Contains data from the All India Pincode Directory, Department of Posts, published on data.gov.in under the Government Open Data License - India.

## Guides

- [Fill city and state from a pincode in a web form](https://api.dharun.dev/guides/pincode-autofill.md): Look up the district and state as soon as someone types a six-digit pincode, with plain JavaScript and no API key.