# Census 2011 figures API

> Population, households, literacy, sex ratio and workers for India, every state, district, sub-district and town, from the 2011 census.

The Primary Census Abstract of the Census of India 2011, the latest count published: households, people by sex, children under seven, Scheduled Castes and Tribes, literacy and work, each as a total and split into rural and urban, with the literacy rate, sex ratio and other rates worked out. 35 states and union territories, 640 districts, 5,923 sub-districts and 7,933 towns, as they were in 2011.

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.

## Figures for a place, and the places inside it

`GET /v1/census/{level}/{code}`

figures holds total, rural and urban (a town has urban only); rates the literacy rate (of people aged 7 and over), sex ratio (females per 1,000 males), child sex ratio, work participation and the urban share. children lists the places one level down with their population. India is /v1/census/india/0.

Parameters:

- `level` (path, required): Which kind of place. One of: india, state, district, subdistrict, town.
- `code` (path, required): The 2011 census code: 33 for Tamil Nadu, 632 for Coimbatore district (from a search).

Example: https://api.dharun.dev/v1/census/district/632?utm_medium=docs-md

Response, with lists and long text shortened:

```json
{
  "data": {
    "level": "district",
    "code": "632",
    "name": "Coimbatore",
    "state": {
      "code": "33",
      "name": "Tamil Nadu"
    },
    "figures": {
      "rural": {
        "agricultural_labourers": 160608,
        "boys": 35589,
        "children": 70035,
        "cultivators": 62494,
        "female_workers": 174678,
        "females": 420073,
        "girls": 34446,
        "household_industry": 18269,
        "households": 242157,
        "literate": 554965,
        "literate_females": 249247,
        "literate_males": 305718,
        "main_workers": 406615,
        "male_workers": 277811,
        "males": 419032,
        "marginal_workers": 45874,
        "non_workers": 386616,
        "other_workers": 211118,
        "persons": 839105,
        "sc": 187055,
        "st": 19622,
        "workers": 452489
      },
      "total": {
        "agricultural_labourers": 230026,
        "boys": 163230,
        "children": 319332,
        "cultivators": 80217,
        "female_workers": 484825,
        "females": 1728748,
        "girls": 156102,
        "household_industry": 50085,
        "households": 958035,
        "literate": 2635907,
        "literate_females": 1241117,
        "literate_males": 1394790,
        "main_workers": 1443252,
        "male_workers": 1083125,
        "males": 1729297,
        "marginal_workers": 124698,
        "non_workers": 1890095,
        "other_workers": 1207622,
        "persons": 3458045,
        "sc": 535911,
        "st": 28342,
        "workers": 1567950
      },
      "urban": {
        "agricultural_labourers": 69418,
        "boys": 127641,
        "children": 249297,
        "cultivators": 17723,
        "female_workers": 310147,
        "females": 1308675,
        "girls": 121656,
        "household_industry": 31816,
        "households": 715878,
        "literate": 2080942,
        "literate_females": 991870,
        "literate_males": 1089072,
        "main_workers": 1036637,
        "male_workers": 805314,
        "males": 1310265,
        "marginal_workers": 78824,
        "non_workers": 1503479,
        "other_workers": 996504,
        "persons": 2618940,
        "sc": 348856,
        "st": 8720,
        "workers": 1115461
      }
    },
    "rates": {
      "literacy_rate": 83.98,
      "male_literacy_rate": 89.06,
      "female_literacy_rate": 78.92,
      "sex_ratio": 1000,
      "child_sex_ratio": 956,
      "work_participation_rate": 45.34,
      "urban_share": 75.73
    },
    "children": [
      {
        "level": "subdistrict",
        "code": "05897",
        "name": "Coimbatore North",
        "population": 637389
      },
      {
        "level": "subdistrict",
        "code": "05898",
        "name": "Coimbatore South",
        "population": 1592646
      },
      {
        "level": "subdistrict",
        "code": "05895",
        "name": "Mettupalayam",
        "population": 260172
      }
    ]
  },
  "meta": {
    "source": {
      "name": "Census of India 2011, Primary Census Abstract (India, states, districts, sub-districts and towns)",
      "url": "https://censusindia.gov.in/nada/index.php/catalog/42559",
      "licence": "Government of India publication, published openly in the Census Digital Library; credited",
      "version": "2011",
      "retrieved": "2026-11-12T15:42:17Z",
      "attribution": "Census of India 2011, Primary Census Abstract, Office of the Registrar General and Census Commissioner, India."
    },
    "note": "Census of India 2011 (Primary Census Abstract), the latest published count. Codes are the 2011 census's: states 2 digits, districts 3, sub-districts 5, towns 6 …"
  }
}
```

## Find a place by name

`GET /v1/census`

Places whose names contain the words, exact names first, then the largest; at most 50, each with its code and population.

Parameters:

- `q` (query, required): 3 to 60 letters, such as madurai.
- `level` (query): Only this kind of place. One of: state, district, subdistrict, town.

Example: https://api.dharun.dev/v1/census?q=coimbatore&utm_medium=docs-md

Response, with lists and long text shortened:

```json
{
  "data": [
    {
      "level": "district",
      "code": "632",
      "name": "Coimbatore",
      "state": {
        "code": "33",
        "name": "Tamil Nadu"
      },
      "population": 3458045
    },
    {
      "level": "subdistrict",
      "code": "05898",
      "name": "Coimbatore South",
      "state": {
        "code": "33",
        "name": "Tamil Nadu"
      },
      "population": 1592646
    },
    {
      "level": "town",
      "code": "803984",
      "name": "Coimbatore (M Corp.)",
      "state": {
        "code": "33",
        "name": "Tamil Nadu"
      },
      "population": 1050721
    }
  ],
  "meta": {
    "total": 4,
    "source": {
      "name": "Census of India 2011, Primary Census Abstract (India, states, districts, sub-districts and towns)",
      "url": "https://censusindia.gov.in/nada/index.php/catalog/42559",
      "licence": "Government of India publication, published openly in the Census Digital Library; credited",
      "version": "2011",
      "retrieved": "2026-11-12T15:42:17Z",
      "attribution": "Census of India 2011, Primary Census Abstract, Office of the Registrar General and Census Commissioner, India."
    },
    "note": "Places whose names contain the words, at most 50, largest first. Census of India 2011 (Primary Census Abstract), the latest published count. Codes are the 2011 …"
  }
}
```

## Data source

- [Census of India 2011, Primary Census Abstract (India, states, districts, sub-districts and towns)](https://censusindia.gov.in/nada/index.php/catalog/42559), 2011, retrieved 2026-11-12T15:42:17Z. Licence: Government of India publication, published openly in the Census Digital Library; credited. Census of India 2011, Primary Census Abstract, Office of the Registrar General and Census Commissioner, India.