Tamil Nadu Village Code Lookup API: names to revenue codes

Example

Request

curl -X POST https://verified.realestate/api/v1/tools/resolve_revenue_codes \
  -H "Authorization: Bearer $LANDLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"village_name":"Kavanoor","taluk_name":"Kundrathur"}'

Responsereal answer

{
  "ok": true,
  "status": "ok",
  "data": {
    "found": true,
    "resolved": {
      "register": "rural",
      "district_name": "Kancheepuram",
      "district_code": "03",
      "taluk_name": "Kundrathur",
      "taluk_code": "14",
      "village_name": "Kavanoor",
      "village_code": "196"
    },
    "confidence": 1,
    "note": "The only place statewide recorded under that name is Kavanoor (Kundrathur taluk, Kancheepuram district). Codes returned are for that entry; give the official spelling and district when you answer. Fuzzy-matched from the revenue catalogs; names shown are the official spellings."
  },
  "credits_charged": 0
}

A real answer from the API (22 Oct 2026).

What it returns

One match returns resolved. Several equal matches return candidates and status not_found, so nothing is picked for you.

Field	What it holds
`resolved.district_code, taluk_code, village_code`	The revenue codes, ready for survey_to_location, fetch_land_record, subdivision_list, fmb_sketch and the rest.
`resolved.district_name, taluk_name, village_name`	The official spellings. Quote these, not the spelling that was typed.
`resolved.register`	rural for a revenue village, urban for a town. Pass it on as rural_urban or register: a taluk numbers its villages and towns separately, and the codes overlap.
`confidence`	How close the match was, from 0 to 1. 1 is an exact, unique match.
`match`	Set when the match was not exact: for example spelling_variant, or the closest spelling in the district asked.
`candidates[], candidates_total`	When more than one place fits: each with its codes, to choose from.
`note, error, next_step`	What the answer means in plain words, and on a miss what to try next.
`needs_english`	Set when a name was sent in Tamil script. The directory is spelled in English; send the English spelling.

Inputs

The JSON body of the POST is the arguments. Send a village name, or a district name. Everything else narrows the match.

Argument	Type	What to send
`village_name`	string	The village or town, e.g. Kavanoor. On its own it is looked up statewide.
`taluk_name`	string	The taluk, when known. It settles namesakes.
`district_name`	string	The district, when known. Leave it out rather than guess.

Code

Set LANDLENS_KEY to your key. In an AI app, connect https://verified.realestate/mcp once and ask in plain words instead. In Postman, download this API's collection, import it (File, Import) and set apiKey.

curl -X POST https://verified.realestate/api/v1/tools/resolve_revenue_codes \
  -H "Authorization: Bearer $LANDLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"village_name":"Kavanoor","taluk_name":"Kundrathur"}'

import os, requests

r = requests.post(
    "https://verified.realestate/api/v1/tools/resolve_revenue_codes",
    headers={"Authorization": f"Bearer {os.environ['LANDLENS_KEY']}"},
    json={
        "village_name": "Kavanoor",
        "taluk_name": "Kundrathur"
    },
    timeout=20,
)
body = r.json()
print(body["status"], body["credits_charged"], body["data"])

const res = await fetch("https://verified.realestate/api/v1/tools/resolve_revenue_codes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LANDLENS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "village_name": "Kavanoor",
    "taluk_name": "Kundrathur"
  }),
});
const body = await res.json();
console.log(body.status, body.credits_charged, body.data);

What are the revenue codes for Kavanoor village in Kundrathur taluk?

Your AI looks the village up and returns its district, taluk and village codes. It is free.

Responses

Every answer has the same envelope. What status can say for this call:

status	What it means
`ok`	One place matched. Use the codes in resolved.
`not_found`	No place matched, or several did (candidates lists them). A miss may mean the name is a locality, not a revenue village: try places_search.
`free_limit_reached`	The account has used its free calls for the hour or the day. retry_after says how many seconds to wait; paid calls keep working.

Where the data comes from

Register

The revenue department's directory of districts, taluks, revenue villages (the A-register) and towns (the town survey land register), in the department's own English spelling.

Coverage

Every district of Tamil Nadu: 38 districts, 303 taluks and 17,237 revenue village entries in the village directory, and 219 towns across 135 taluks in the town directory.

How current

Read from our copy of the directory. Villages and towns change only when the government creates, splits or renames one, and the copy is refreshed when that happens.

How we read it

Each name is scored against the directory, so minor misspellings still match. A district or taluk given by the caller narrows the search but never forces a wrong pick: an exact, unique village name elsewhere in the state wins over a fuzzy match in the guessed district.

Who uses it

Developers

Turn the village a user types into codes once, then chain every land record call off them.

Document readers

Map the village named in a deed or patta to its codes before fetching the record.

AI assistants

Resolve a place name a user mentions without asking them for a district they may not know.

Limits and good practice

A locality name (Velachery, Adyar) is often not a revenue village. When the lookup misses, use places_search for a point and resolve_parcel on it.
Several places can share a name. The API lists them rather than picking; ask the user or add the taluk.
Old or renamed districts in older deeds are better served by map_registration_to_revenue.
Names in Tamil script are not matched; send the English spelling the revenue records use.

Pricing

Free

The village code lookup costs nothing. Free calls have their own allowance per hour and per day. Credits come from the same LandLens wallet as the chat and the minis. How billing works.

Calling at volume?

Free calls have an hourly and daily allowance. For more than that, or a platform built on these registers, we set up limits and a plan to match.

WhatsApp 99961 29996