Village Profile API: parcels and government land

Example

Request

curl -X POST https://verified.realestate/api/v1/tools/village_xray \
  -H "Authorization: Bearer $LANDLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"district_code":"03","taluk_code":"14","village_code":"196","village_name":"Kavanoor"}'

Responsereal answer

{
  "ok": true,
  "status": "ok",
  "data": {
    "found": true,
    "village_name": "Kavanoor",
    "total_parcels": 3745,
    "sampled_parcels": 3745,
    "unique_surveys": 256,
    "government_parcels": 23,
    "government_pct": 0.6,
    "private_parcels": 1266,
    "private_pct": 33.8,
    "unclassified_parcels": 2456,
    "unclassified_pct": 65.6,
    "land_types": {
      "Unclassified": 2456,
      "Wet": 863,
      "Dry": 405,
      "Poramboke": 21
    },
    "truncated": false,
    "note": "Counts are cadastral map parcels (subdivisions), not owners. Government parcels are poramboke (roads, waterbodies, government land). The interface renders the composition card with the splits."
  },
  "credits_charged": 1
}

A real answer from the API (22 Oct 2026, Kavanoor village, Kundrathur taluk).

What it returns

One village, counts and percentages. Counts are parcels (sub-divisions), not owners.

Field	What it holds
`total_parcels, sampled_parcels`	Active parcels in the village, and how many were counted.
`unique_surveys`	Distinct survey numbers.
`government_parcels, government_pct`	Parcels classified as government land (roads, water bodies, government land), and their share.
`private_parcels, private_pct`	Parcels classified as private (ryotwari) land, and their share.
`unclassified_parcels, unclassified_pct`	Parcels the layer gives no classification, and their share.
`land_types`	Parcels by land type: Wet, Dry, Natham, Poramboke, Unclassified.
`truncated`	true when the village has more parcels than were counted, so the percentages are over a sample.
`village_name`	The name you sent, for a card title.

Inputs

The JSON body of the POST is the arguments. The three revenue codes are required. resolve_revenue_codes gives them for village names; resolve_parcel for a map point.

Argument	Type	What to send
`district_code`required	string
`taluk_code`required	string
`village_code`required	string
`village_name`	string	Optional. Echoed back for a card title.

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/village_xray \
  -H "Authorization: Bearer $LANDLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"district_code":"03","taluk_code":"14","village_code":"196","village_name":"Kavanoor"}'

import os, requests

r = requests.post(
    "https://verified.realestate/api/v1/tools/village_xray",
    headers={"Authorization": f"Bearer {os.environ['LANDLENS_KEY']}"},
    json={
        "district_code": "03",
        "taluk_code": "14",
        "village_code": "196",
        "village_name": "Kavanoor"
    },
    timeout=60,
)
body = r.json()
print(body["status"], body["credits_charged"], body["data"])

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

How much of Kavanoor village in Kundrathur taluk is government land, and what is its wet and dry split?

Your AI finds the village codes, says the price, and charts the split.

Responses

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

status	What it means
`ok`	The village has active parcels on the map. Charged 1 credit.
`not_found`	No active cadastral parcels were found for the village codes. Nothing is charged.
`invalid_args`	A revenue code is missing.

Where the data comes from

Register

The state cadastral boundary layer (FMB) for Tamil Nadu, with the government or private classification and land type recorded against each parcel.

Coverage

Revenue villages across Tamil Nadu that the cadastral layer covers. Active parcels only.

How current

Read from the copy of the state cadastral layer we hold.

How we read it

Every active parcel of the village is read (up to 6,000) and counted. Parcels without a government or private classification are counted as unclassified. A larger village is profiled over its first 6,000 parcels, and truncated says so.

Who uses it

Developers and land aggregators

Size up a village before a land search: how many parcels, how much is government, how much is wet land.

Analysts and planners

Compare villages by their government share and land type mix.

Limits and good practice

Counts are map parcels (sub-divisions), not owners or holdings.
Many parcels carry no classification in the layer. Read the unclassified share before drawing a conclusion from the government and private split.
Villages with more than 6,000 parcels are profiled over their first 6,000; truncated says so.
A whole-village figure. For one parcel, use plot_owner or land_quality.

Pricing

1 credit per answer

Each village profiled costs 1 credit; nothing when no parcels are found. Credits come from the same LandLens wallet as the chat and the minis. How billing works.

Calling at volume?

For thousands of calls a month, a portfolio sweep or a platform built on these registers, we quote a customised bulk price, with invoicing to match.

WhatsApp 99961 29996