API documentation

Five GET endpoints, one JSON envelope shape, no authentication. No API key, CORS open, rate limit 100 requests per 15 minutes per IP.

OpenAPI 3.1 JSON contract

Endpoints

Endpoint	Parameters	Notes
GET /v1/states	none	All 36 states and union territories with LGD codes.
GET /v1/districts	?state (optional)	Districts of one state, or every district in India if unfiltered.
GET /v1/subdistricts	?district or ?state (one required)	Sub-districts (tehsils). Omitting both filters returns 400. If both are used, they must agree.
GET /v1/blocks	?district or ?state (one required)	Development blocks. Omitting both filters returns 400. If both are used, they must agree.
GET /v1/search	?q (required)	Case-insensitive substring match across all four levels, grouped by level, each row carrying its parent chain. Query text is 1–100 characters. Capped at 50 matches per level with a truncated flag.

Envelopes

Success responses wrap rows in data with a meta object carrying the row count and data freshness:

Success envelope · shape

{
  "success": true,
  "data": [
    {
      "code": "18",
      "name": "WEST BENGAL"
    }
  ],
  "meta": {
    "count": 1,
    "source_date": "23Sep2026",
    "ingested_at": "2026-09-24T…",
    "attribution": {
      "source": "Ministry of Panchayati Raj — LGD",
      "license": "GODL-India"
    }
  }
}

Errors are uniform across every failure mode — missing params, unknown codes, unknown routes, rate limiting — always with a stable machine-readable error.code:

Error envelope · shape

{
  "success": false,
  "error": {
    "code": "MISSING_PARAM",
    "message": "…"
  }
}

Error codes

Code	HTTP	When
MISSING_PARAM	400	A required query parameter is absent or empty.
INVALID_QUERY_PARAM	400	An unknown, repeated, empty, or malformed query parameter.
FILTER_MISMATCH	400	The district does not belong to the supplied state.
URI_TOO_LONG	414	The request URL exceeds 2,048 characters.
INVALID_STATE_CODE	404	A ?state value that is not a valid LGD state code.
INVALID_DISTRICT_CODE	404	A ?district value that is not a valid LGD district code.
ENDPOINT_NOT_FOUND	404	Any route outside the documented set.
TOO_MANY_REQUESTS	429	More than 100 requests in 15 minutes from one IP.

Data notes

Rows preserve normalized LGD names and carry the government LGD codes. One upstream quirk to know before you build: block codes are not nationally unique — the source data reuses a small number of block codes across different districts — so treat (state, district, code) as the block identity. State and district codes are nationally unique.

An automated refresh is scheduled for Monday 03:00 UTC from the upstream mirror. Check meta.source_date on any response to see which upstream edition you are reading.

Attribution (required)

This API redistributes Government of India data under the Government Open Data License – India (GODL). Any public use must credit the source and link back to it:

Ministry of Panchayati Raj — Local Government Directory · GODL-India license · data mirror

Quickstart

curl "https://india-lgd-index-api.vercel.app/v1/districts?state=18"