# Address reader API

> A free-text Indian address split into house, street, locality, city, state and pincode, checked.

Splits a written address into its parts and checks the pincode against the post office list: a pincode in another state, or a city that is not near the pincode, is flagged. Rules, not a model. What you send is never logged.

Base URL `https://api.dharun.dev`. No API key needed for most endpoints; a free key (https://api.dharun.dev/keys) raises the limits, and the model endpoints marked below will need one. Answers are JSON, `{ "data": ..., "meta": { ... } }`, and errors are `{ "error": { "code", "message" } }` with a matching HTTP status. Rate limit: 600 units a minute per address without a key, 3000 per key; the `RateLimit-*` headers say what is left.

## Read an Indian address

`GET /v1/address/parse`, also `POST`

POST body: The address, as text/plain or JSON {"text": "..."}. Send it as `text/plain`, or as JSON `{"text": "..."}` with the other options beside it.

What you send is never written to the log, and the answer is not cached.

Parameters:

- `text` (query): The address.

Example: https://api.dharun.dev/v1/address/parse?text=12%2C%20Anna%20Salai%2C%20Mount%20Road%2C%20Chennai%2C%20Tamil%20Nadu%20600002&utm_medium=docs-md

Response:

```json
{
  "data": {
    "input": "12, Anna Salai, Mount Road, Chennai, Tamil Nadu 600002",
    "house": "12",
    "street": "Anna Salai",
    "locality": "Mount Road",
    "city": "Chennai",
    "district": "Chennai",
    "state": "Tamil Nadu",
    "pincode": "600002",
    "pincodeChecked": true,
    "postOffices": [
      "Anna Road H.O",
      "Chintadripet",
      "MADRAS ELECTRICITY SYSTEM"
    ],
    "warnings": []
  },
  "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."
    },
    "note": "Read by rules, not a model: the parts are guesses from commas and common words, checked against the pincode. What you send is never logged."
  }
}
```

## 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.