Villages API

Village-level point data used as the seed for the cluster generator. Each village has a GPS point and member counts for six commodities (Dairy, Goatery, Piggery, Backyard Poultry, Duckery, Fishery Activity).

Data source

Village records are loaded from data/villages.csv, the cluster planner's source of truth (~21,495 rows). It is built from the SHG survey workbook (scripts/build_village_master.py) and spans 35 districts and 220 blocks across Assam. District/block names are taken verbatim from the survey (uppercased, whitespace-collapsed); rows with missing or out-of-range coordinates are dropped.

---

List Villages

GET /api/villages

Returns village rows with district, block, GP, name, lat/long, and per-commodity member counts. With no block filter, the full village master is returned.

Query Parameters

Param	Type	Required	Description
block	string	No	Filter to villages within a single block. Match on block_name is case-insensitive and whitespace-trimmed.

Response

[
  {
    "district_name": "DIBRUGARH",
    "block_name": "KHOWANG",
    "gp_name": "DIKHARI TILOI",
    "vill_name": "DIKHARI MORAN NO.1",
    "lat": 27.30832984,
    "long": 94.88209863,
    "Dairy": 3,
    "Goatery": 9,
    "Piggery": 10,
    "Backyard_Poultry": 3,
    "Duckery": 2,
    "Fishery_Activity": 1
  }
]

Additional "other activity" columns present in the village master (e.g. Fodder, Feed, Livestock transport, Meat shop) are returned as-is alongside the six commodity columns.

Example

cURLPython

curl "https://leaf-asrlm.in/api/villages?block=KHOWANG"

import requests
rows = requests.get("https://leaf-asrlm.in/api/villages",
                    params={"block": "KHOWANG"}).json()
print(len(rows), "villages")

---

Villages as GeoJSON

GET /api/villages/geojson

Same data as /api/villages, formatted as a GeoJSON FeatureCollection of Point features. Drop straight into Leaflet/Mapbox.

Query Parameters

Param	Type	Required	Description
block	string	No	Filter to villages within a single block (case-insensitive, whitespace-trimmed).

Response

Each feature's geometry.coordinates is [long, lat]. All village columns except lat/long are copied into properties (with NaN values normalised to null).

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [94.88209863, 27.30832984] },
      "properties": {
        "district_name": "DIBRUGARH",
        "block_name": "KHOWANG",
        "gp_name": "DIKHARI TILOI",
        "vill_name": "DIKHARI MORAN NO.1",
        "Dairy": 3,
        "Goatery": 9,
        "Piggery": 10,
        "Backyard_Poultry": 3,
        "Duckery": 2,
        "Fishery_Activity": 1
      }
    }
  ]
}

---

Aggregated Counts

GET /api/villages/aggregate

Drives the state- and district-scale map levels. At state scale, rendering ~21k points is meaningless, so the map shows aggregated numbers per district; at district scale, the same per block. Village points are only rendered at block scale. Each row sums villages and members per commodity within the group.

Query Parameters

Param	Type	Required	Description
level	string	Yes	district (one row per district) or block (one row per (district, block)). Any other value returns 400.
district	string	No	Restrict aggregation to one district (exact match on district_name). Applies at either level.

Response

[
  {
    "district_name": "DIBRUGARH",
    "block_name": "KHOWANG",
    "village_count": 275,
    "Dairy": 175,
    "Goatery": 4756,
    "Piggery": 6263,
    "Backyard_Poultry": 2218,
    "Duckery": 2320,
    "Fishery_Activity": 407
  }
]

block_name is omitted when level=district.

Code	Description
200	Array of aggregated rows.
400	Missing or invalid level (must be district or block).
500	Server error (e.g. village data file missing).

---

Blocks With Village Data

GET /api/villages/blocks

Lists every (district, block) pair present in the village master, with a village count. Use this to drive the block-scale drill-down.

Response

[
  { "district_name": "DIBRUGARH", "block_name": "KHOWANG", "village_count": 275 }
]

Code	Description
200	Array of block summaries.
500	Server error (e.g. village data file missing).

---

Errors

Code	Description
400	/api/villages/aggregate only — level missing or not district/block.
500	Village data file missing or unreadable, or an unexpected server error. Body: { "error": "<message>" }.