| Title: | Census of India Data, 1901-2011, with Boundaries and Projections |
|---|---|
| Description: | Tables from every decennial Census of India from 1901 to 2011: population time series, Primary Census Abstracts at state, district and sub-district level, mother tongue tables, Scheduled Caste and Scheduled Tribe populations, and the 1931 caste tables by religion, together with Ministry of Health and Family Welfare population projections to 2036. Historical series are drawn from Jolad and Singh (2026) <doi:10.7910/DVN/ON8CP8>. Census variables can be returned with state or district boundaries of the matching census year attached for mapping. Boundary files and the largest village-level tables are downloaded on first use and cached locally. |
| Authors: | Saket Choudhary [aut, cre, cph] (ORCID: <https://orcid.org/0000-0001-5202-7633>) |
| Maintainer: | Saket Choudhary <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.1 |
| Built: | 2026-10-11 20:34:28 UTC |
| Source: | https://github.com/saketlab/censusindia |
The village-level 2011 tables (census_2011_demographics(),
census_2011_workers(), census_2011_marginal_detail()) stack seven levels
from India down to ward, and three sectors. Summing without filtering counts
every population several times over. census_1981 stacks levels and sectors
the same way.
at_level(data, level = "district", sector = "total")at_level(data, level = "district", sector = "total")
data |
A table with a |
level |
Geographic level, e.g. |
sector |
|
India, state, district, subdistrict and village are exact: each level sums to its parent for every numeric column, and rural + urban sums to total.
"town" and "ward" are not. The census files a municipality and that same
municipality plus its outgrowth as separate town rows, so the two overlap.
Summing towns to their subdistrict overcounts 325 subdistricts by 73,877,047
people in total; Bengaluru's BBMP (M Corp.) and BBMP (M Corp. + OG) each
carry 8,443,675. Ward rows differ from their town by 3,738,272 across 295
towns. Treat both as a lookup, not an additive slice.
data filtered to that level and sector.
census_1981 |> at_level("state") |> nrow()census_1981 |> at_level("state") |> nrow()
Adds geometry for mapping. Auto-detects state or district level from available columns.
attach_geometry( data, year, geography = NULL, unmatched = c("warn", "error", "ignore") )attach_geometry( data, year, geography = NULL, unmatched = c("warn", "error", "ignore") )
data |
A data frame containing census data with state/district names. |
year |
Census year for boundaries. Available: 1941, 1951, 1961, 1971, 1981, 1991, 2001, 2011. |
geography |
Geographic level: "state" or "district". If NULL (default), auto-detects based on available columns. |
unmatched |
What to do when rows get no geometry, or when two rows are
given the same polygon: |
An sf object with geometry attached.
Boundary files are downloaded on first use; see census_cache_dir().
# Attach district boundaries census_2011_pca |> dplyr::mutate(st_pct = 100 * st_population / population_total) |> attach_geometry(2011)# Attach district boundaries census_2011_pca |> dplyr::mutate(st_pct = 100 * st_population / population_total) |> attach_geometry(2011)
Population of every caste and community listed in the caste tables of the 1931 Census, cross-classified by religion, for 24 provinces, princely states and agencies of British India.
census_1931_castescensus_1931_castes
A tibble with 2,226 rows and 17 columns:
Census year (1931)
Province, princely state or agency, standardised
"British Province", "Princely State" or "Agency"
Caste or community as printed
Position in the province's ranked caste list, 1 the largest
Persons
of the caste returned under each religion; tribal is the 1931 "Tribal"
or "Primitive" religion return
Sum of the religion columns
Total printed in the province's ranked list; NA for the Andaman & Nicobar Islands
Compiler's flag, for example where total and
total_ranked_list disagree
A religion column is NA where the province's table has no column for that
religion, and 0 where the column exists and no one was returned. Ajmer-Merwara
has totals only, so its religion columns and total are NA. Residual
entries such as "Caste Unspecified" and "Indian Christian" are rows of their
own.
Jolad, Shivakumar, Kalyani, Gaurav and Baharadia, Samarth (2026). "Database of castes." Harvard Dataverse. doi:10.7910/DVN/WT5VIY. Digitised from the provincial, princely state and agency reports of the Census of India, 1931.
Castes and tribes the 1931 Census treated as exterior, with their population, by province or state section of Appendix I of the Census of India 1931, Volume I. "Exterior castes" is the report's term.
census_1931_exterior_castescensus_1931_exterior_castes
A tibble with 533 rows and 5 columns:
Census year (1931)
Province or state section of the appendix
Caste or tribe as printed, with bracketed qualifiers
Persons treated as exterior
Compiler's remark
Jolad, Shivakumar, Kalyani, Gaurav and Baharadia, Samarth (2026). "Database of castes." Harvard Dataverse. doi:10.7910/DVN/WT5VIY. Census of India, 1931, Volume I, Appendix I: Exterior Castes.
District-level literacy rates from the 1961 Census.
census_1961_literacycensus_1961_literacy
A tibble with 347 rows and 8 columns:
Census year (1961)
Name of the state
Harmonized state name for joining across datasets
Name of the district
Combined state-district code
Total literacy rate (percent)
Male literacy rate (percent)
Female literacy rate (percent)
Jolad, Shivakumar and Singh, Madhav (2026). "Indian Census Data Collection, 1901-2026: Digitised Subnational Population and Administrative Datasets." Harvard Dataverse. doi:10.7910/DVN/ON8CP8.
State and district population from the 1971 Census with rural/urban breakdown and SC/ST populations.
census_1971census_1971
A tibble with 370 rows and 21 columns:
Census year (1971)
Geographic level: "state" or "district"
Name of the state
Harmonized state name for joining across datasets
Name of the state or district
Area in square kilometers
Total population
Rural population
Urban population
Total male population
Rural male population
Urban male population
Total female population
Rural female population
Urban female population
Total Scheduled Caste population
Rural Scheduled Caste population
Urban Scheduled Caste population
Total Scheduled Tribe population
Rural Scheduled Tribe population
Urban Scheduled Tribe population
Population, males and females partition exactly into rural and urban. The
SC/ST columns do not: one sc_population row and five st_population rows
fail rural + urban == total, the largest gaps being 493,272 (Hooghly, SC)
and 472,910 (Jhabua, ST). District coverage is also short of the state total
for Mysore and Tamil Nadu.
Jolad, Shivakumar and Singh, Madhav (2026). "Indian Census Data Collection, 1901-2026: Digitised Subnational Population and Administrative Datasets." Harvard Dataverse. doi:10.7910/DVN/ON8CP8.
State and district data from the 1981 Census with literacy and worker classification.
census_1981census_1981
A tibble with 2,364 rows and 39 columns including:
Census year (1981)
Unique geographic identifier
Name of the geographic unit
Geographic level (india, state, district)
Name of the state
Harmonized state name for joining across datasets
Name of the district (if applicable)
Sector: "total", "rural", or "urban"
Area in square kilometers
Total population
Male population
Female population
Total literate population
Total main workers
Total cultivators
Total agricultural labourers
Household industry workers
Other workers
Non-workers
The source is OCR'd and carries transcription errors. Of 420 rows with a
rural and urban counterpart, 83 fail rural + urban == total; the largest
gap is 101,809,324 in Himachal Pradesh non_workers_males, a powers-of-ten
slip rather than rounding. District sums disagree with the state row in 19 of
30 states. Check any column you rely on before trusting it.
Jolad, Shivakumar and Singh, Madhav (2026). "Indian Census Data Collection, 1901-2026: Digitised Subnational Population and Administrative Datasets." Harvard Dataverse. doi:10.7910/DVN/ON8CP8.
District-level population, SC/ST, literacy, and worker statistics from
the 2001 Census. Covers 593 districts; population_total sums to
1,028,610,328, the 2001 India total.
census_2001_pcacensus_2001_pca
A tibble with 593 rows and 19 columns:
Census year (2001)
Geographic level ("district")
Numeric state code
Name of the state
Harmonized state name for joining across datasets
Numeric district code
Name of the district
Number of households
Total population
Male population
Female population
Population aged 0-6 years
Scheduled Caste population
Scheduled Tribe population
Total literate population
Total workers
Main workers
Marginal workers
Non-workers
Use 2001 boundaries with attach_geometry(). Districts are 2001 vintage,
so the 2011 boundary file has no polygon for several of them and will
mismatch others: North Cachar Hills (renamed Dima Hasao in 2010) and an
undivided Medinipur (split into Purba and Paschim in 2002) both resolve
to the wrong 2011 district. See census_2011_pca for the 2011 round.
Until version 0.0.0.9000 this table shipped as census_2011_pca with a
hard-coded year of 2011.
Census of India 2001, Primary Census Abstract.
The complete published 2001 PCA at district level: every indicator split by sex, and each district given for total, rural and urban. 593 districts x 3 sectors = 1,779 rows.
census_2001_pca_fullcensus_2001_pca_full
A tibble with 1,779 rows and 47 columns. Beyond the identifiers
(year, geography, state_code, state_name, district_code, name,
sector) each indicator appears with a _total, _male and _female suffix:
Number of households
Total population
Population aged 0-6 years
Scheduled Caste population
Scheduled Tribe population
Literate population
Illiterate population
All workers
Main workers
Marginal workers
Main workers by category
Marginal workers by category
Non-workers
census_2001_pca is the narrower 19-column view of the same data, kept for the columns it shares with census_2011_pca.
Census of India 2001, Primary Census Abstract (series
PC01_PCA_TOT).
Population, SC/ST, and literacy counts from the 2011 Primary Census
Abstract at all geographic levels (India, state, district, subdistrict,
town/village, ward), split by total/rural/urban sector. Downloaded on first
use; see census_cache_dir(). Use at_level() before summing.
census_2011_demographics()census_2011_demographics()
A tibble with 751,594 rows and 28 columns:
Numeric state code
Numeric district code
Numeric subdistrict code
Town or village code
Ward code
Geographic level (india, state, district, subdistrict, town, village, ward)
Name of the geographic unit
Harmonized state name for joining across datasets
Sector: "total", "rural", or "urban"
Number of households
Total, male, and female population
Population aged 0-6 years
Scheduled Caste population
Scheduled Tribe population
Literate population
Illiterate population
Census of India 2011, Primary Census Abstract.
census_2011_demographics() |> at_level("state")census_2011_demographics() |> at_level("state")
Mother tongue speakers by language at district level from the 2011 Census C-16 tables, with male/female and rural/urban breakdowns.
census_2011_district_languagescensus_2011_district_languages
A tibble with 38,993 rows and 11 columns:
Numeric state code
Harmonized state name for joining across datasets
Numeric district code
Name of the language
Numeric language group code
Total speakers
Male speakers
Female speakers
Rural speakers
Urban speakers
Name of the district
Census of India 2011, C-16 Mother Tongue Tables.
District-level linguistic diversity metrics derived from the 2011 Census
C-16 mother tongue tables, counting named mother tongues only. C-16 files
the unscheduled languages of the northeast under per-group "Others"
residuals, which carry no language name and are excluded; coverage
reports the share of the district the metrics are computed from, and falls
below 0.9 in 34 districts and below 0.5 in 7.
census_2011_linguistic_diversitycensus_2011_linguistic_diversity
A tibble with 640 rows and 11 columns:
Harmonized state name for joining across datasets
Numeric state code
Numeric district code
Number of distinct languages spoken
Total speakers across all languages
Shannon entropy of the language distribution
Effective number of languages (2^shannon_entropy)
Most-spoken language
Share of speakers of the dominant language
Name of the district
Share of district population in named mother tongues
Census of India 2011, C-16 Mother Tongue Tables (derived).
Marginal workers from the 2011 Primary Census Abstract split by duration
of work (3-6 months and 0-3 months) and by activity, plus non-workers,
at all geographic levels and total/rural/urban sector. Downloaded on first
use; see census_cache_dir(). Use at_level() before summing.
census_2011_marginal_detail()census_2011_marginal_detail()
A tibble with 751,594 rows and 42 columns:
Geographic codes
Geographic level (india, state, district, subdistrict, town, village, ward)
Name of the geographic unit
Harmonized state name for joining across datasets
Sector: "total", "rural", or "urban"
Marginal workers employed 3-6 months
Marginal cultivators, 3-6 months
Marginal agricultural labourers, 3-6 months
Marginal household industry workers, 3-6 months
Marginal other workers, 3-6 months
Marginal workers employed 0-3 months
Marginal cultivators, 0-3 months
Marginal agricultural labourers, 0-3 months
Marginal household industry workers, 0-3 months
Marginal other workers, 0-3 months
Non-workers
Census of India 2011, Primary Census Abstract.
census_2011_marginal_detail() |> at_level("state")census_2011_marginal_detail() |> at_level("state")
Mother tongue speakers by language at state and district levels from the
2011 Census C-16 tables, with rural/urban and male/female breakdowns.
Downloaded on first use; see census_cache_dir(). For per-district
or per-subdistrict counts that sum correctly, use census_languages().
census_2011_mother_tongue()census_2011_mother_tongue()
A tibble with 350,157 rows and 18 columns:
Numeric state code
Name of the state
Harmonized state name for joining across datasets
District code ("000" for state total)
Name of the state or district
Census language code
Name of the language or dialect
L1 for main languages, L2 for dialects
Numeric language group code
Total speakers
Male speakers
Female speakers
Rural speakers
Rural male speakers
Rural female speakers
Urban speakers
Urban male speakers
Urban female speakers
Census of India 2011, C-16 Mother Tongue Tables.
census_2011_mother_tongue() |> head()census_2011_mother_tongue() |> head()
District-level population, SC/ST, literacy, and worker statistics from
the 2011 Census. Covers all 640 districts; population_total sums to
1,210,854,977, the 2011 India total.
census_2011_pcacensus_2011_pca
A tibble with 640 rows and 19 columns:
Census year (2011)
Geographic level ("district")
Numeric state code
Name of the state
Harmonized state name for joining across datasets
Numeric district code
Name of the district
Number of households
Total population
Male population
Female population
Population aged 0-6 years
Scheduled Caste population
Scheduled Tribe population
Total literate population
Total workers
Main workers
Marginal workers
Non-workers
Aggregated at district level from the village-level 2011 PCA that also
backs census_2011_demographics(), census_2011_workers() and
census_2011_marginal_detail(). For the 2001 round see census_2001_pca.
Jolad, Shivakumar and Singh, Madhav (2026). "Indian Census Data Collection, 1901-2026: Digitised Subnational Population and Administrative Datasets." Harvard Dataverse. doi:10.7910/DVN/ON8CP8.
District-level Scheduled Caste and Scheduled Tribe population from the 2011 Census A-10 and A-11 tables.
census_2011_sc_stcensus_2011_sc_st
A tibble with 14,028 rows and 9 columns:
Census year (2011)
Harmonized state name for joining across datasets
Name of the district
"Scheduled Caste" or "Scheduled Tribe", spelled out
"SC" or "ST", for filtering by the short form
Name of the caste or tribe
Population of the caste or tribe
Share of district population
Total district population
The two categories are not symmetric. Scheduled Tribes are enumerated by
name, 581 of them. Scheduled Castes are not: all 582 SC rows carry the single
label "All Scheduled Castes", one per district. Nothing in this package
resolves caste below that aggregate.
Filter with either spelling: category holds the long form, category_code
holds SC/ST. census_sc_st() accepts both.
ST rows include "Generic Tribes etc.", the residual for members who
returned no specific tribe: 585 rows, 2,804,148 people.
census_2011_tribes is this table's ST rows with that residual removed and
the names harmonised.
Census of India 2011, A-10 (SC) and A-11 (ST) tables.
Mother tongue speakers by language at subdistrict level from the 2011
Census C-16 tables, with male/female and rural/urban breakdowns. The
district rows that share each subdistrict's district_code are excluded,
so these rows sum to the matching row of census_2011_district_languages.
Downloaded on first use; see census_cache_dir().
census_2011_subdistrict_languages()census_2011_subdistrict_languages()
A tibble with 144,134 rows and 11 columns:
Numeric state code
Harmonized state name for joining across datasets
Numeric district code
Name of the subdistrict
Name of the language
Numeric language group code
Total speakers
Male speakers
Female speakers
Rural speakers
Urban speakers
Census of India 2011, C-16 Mother Tongue Tables.
census_2011_subdistrict_languages() |> head()census_2011_subdistrict_languages() |> head()
District-level population of individual Scheduled Tribes from the 2011
Census A-11 tables. tribe_name is harmonised; tribe_name_original keeps
the source string verbatim, including the full synonym list the census
publishes ("Gond, Arakh, Arrakh, Agaria, ...") and any parenthetical
district qualifier.
census_2011_tribescensus_2011_tribes
A tibble with 12,861 rows and 8 columns:
Census year (2011)
Harmonized state name for joining across datasets
Name of the district
Harmonized tribe name
Original tribe name as recorded in the source
Tribe population
Share of district population
Total district population
Harmonisation takes the first synonym and drops the qualifier, so
"Thoti (in Adilabad, Hyderabad, ...)" becomes "Thoti". That collapses 581
source strings to 483 tribe names, and it is deliberate: the same tribe is
written differently across states, sometimes differing only in whitespace.
These are the ST rows of census_2011_sc_st with "Generic Tribes etc."
removed, which is why the population here sums to 103,409,280 rather than the
106,213,428 in that table. Neither figure equals the 104,545,716 in
census_2011_pca$st_population; the A-11 tables and the Primary Census
Abstract do not reconcile, so pick one source per analysis and say which.
Census of India 2011, A-11 Scheduled Tribe tables.
Worker classification from the 2011 Primary Census Abstract at all
geographic levels, split by total/rural/urban sector. Main and marginal
workers are broken down by activity (cultivators, agricultural labourers,
household industry, other workers). Downloaded on first use; see
census_cache_dir(). Use at_level() before summing.
census_2011_workers()census_2011_workers()
A tibble with 751,594 rows and 42 columns:
Geographic codes
Geographic level (india, state, district, subdistrict, town, village, ward)
Name of the geographic unit
Harmonized state name for joining across datasets
Sector: "total", "rural", or "urban"
All workers
Main workers
Main cultivators
Main agricultural labourers
Main household industry workers
Main other workers
Marginal workers
Marginal cultivators
Marginal agricultural labourers
Marginal household industry workers
Marginal other workers
Census of India 2011, Primary Census Abstract.
census_2011_workers() |> at_level("state")census_2011_workers() |> at_level("state")
A ggplot2 layer of the state polygons for a census year, drawn as flat
fill. Put it under a district choropleth so the national outline stays whole:
the census enumerates no districts in the territory India claims but does not
administer, so a district layer alone truncates the north by roughly two
degrees of latitude.
census_base_layer(year, fill = "grey80", ...)census_base_layer(year, fill = "grey80", ...)
year |
Census year whose boundaries to draw. One of 1941, 1951, 1961, 1971, 1981, 1991, 2001, 2011. |
fill |
Fill colour for the base. Defaults to the grey |
... |
Passed to |
plot_map() adds this automatically. Use it directly when hand-rolling a map
with ggplot2::geom_sf().
A ggplot2 layer.
ggplot2::ggplot() + census_base_layer(2011)ggplot2::ggplot() + census_base_layer(2011)
Census boundaries and the seven largest tables are downloaded on first use, checked against a pinned MD5 checksum, and kept here for later sessions.
census_cache_dir() clear_census_cache()census_cache_dir() clear_census_cache()
The cache lives in tools::R_user_dir(). Set the option
censusindia.cache_dir to use another directory.
census_cache_dir() returns the cache path, which may not exist
yet. clear_census_cache() deletes it and invisibly returns that path.
census_download() to fetch everything at once;
clear_geometry_cache() to release what the session holds in memory.
census_cache_dir()census_cache_dir()
Fetches every boundary file and large table not yet in census_cache_dir(),
so later calls work offline.
census_download()census_download()
The cache directory, invisibly.
census_download()census_download()
The C-16 mother tongue tables stack state, district and subdistrict rows,
and a subdistrict carries its parent's district_code. Filtering on
district_code != "000" therefore keeps subdistricts too, and summing the
result double counts: 640 districts become 6,231 rows, and district totals
inflate by a median factor of two.
census_languages(level = c("district", "subdistrict"), language_group = NULL)census_languages(level = c("district", "subdistrict"), language_group = NULL)
level |
|
language_group |
Optionally restrict to one language group, as listed in
the |
area_name does not separate the two levels either, because in 392 of the
640 districts the headquarters tehsil carries the district's own name.
Subdistricts do partition their district, so the district value for any
(district_code, language_code) is half the group sum. The tables this
returns are that split, applied once at build time.
A tibble at the requested level, one row per language per area.
census_2011_linguistic_diversity for one row per district with entropy already computed.
census_languages("district") |> head()census_languages("district") |> head()
Decadal population at state and district levels, 1901-2011.
census_population_time_seriescensus_population_time_series
A tibble with 7,901 rows and 12 columns:
Census year (1901, 1911, ..., 2011)
Geographic level: "state" or "district"
Numeric state code
Name of the state
Harmonized state name for joining across datasets
Numeric district code (0 for state-level)
Name of the state or district
Total population
Male population
Female population
Absolute change from previous census
Percentage change from previous census
Sikkim, Mizoram and Daman & Diu are absent from every year, so 2011 sums to
1,208,903,947 across 626 districts rather than 1,210,854,977 across 640.
get_census() uses the Primary Census Abstract for 2001 and 2011 instead.
District rows also fall short of their state totals before 1961 (57 districts
carry no population in 1901-1941) and in 1981, where all 27 Assam districts
are missing while the state estimate is present. The year column further
carries 1900, 1910, 1940, 1948, 1950, 1960, 1962 and 2021, which are not
censuses; use census_years() before any lag().
Jolad, Shivakumar and Singh, Madhav (2026). "Indian Census Data Collection, 1901-2026: Digitised Subnational Population and Administrative Datasets." Harvard Dataverse. doi:10.7910/DVN/ON8CP8.
census_2011_sc_st stores category as "Scheduled Caste" and
"Scheduled Tribe". filter(category == "SC") therefore matches nothing and
raises no error. This accessor takes either spelling, in any case, and the
table itself now carries a category_code column holding SC/ST so plain
dplyr::filter() works both ways too.
census_sc_st(category = NULL, state = NULL)census_sc_st(category = NULL, state = NULL)
category |
|
state |
Optionally restrict to one or more states, by canonical name or
two-letter code, as in |
The two categories are not symmetric. Scheduled Tribes are named, 581 of
them. All 582 Scheduled Caste rows carry the single label
"All Scheduled Castes", one per district, so "SC" returns district
aggregates rather than individual castes.
A tibble of census_2011_sc_st rows.
census_2011_tribes for the ST rows with names harmonised and the
"Generic Tribes etc." residual removed.
nrow(census_sc_st("SC")) nrow(census_sc_st("Scheduled Caste"))nrow(census_sc_st("SC")) nrow(census_sc_st("Scheduled Caste"))
Subdistrict (tehsil/taluka) population from the 2011 Census.
census_subdistricts_2011census_subdistricts_2011
A tibble with 5,988 rows and 15 columns:
Census year for population data (2011)
Geographic level ("subdistrict")
Name of the state
Harmonized state name for joining across datasets
Name of the district
Name of the subdistrict (tehsil/taluka)
Total population
Male population
Female population
Number of households
Number of inhabited villages
Number of uninhabited villages
Number of towns
Area in square kilometers
Population density per square kilometer
A subdistrict crossing a district line is listed once per district, marked
"(Part)". Population, males, females and households come from
census_2011_demographics() and sum to census_2011_pca. Villages, towns,
area and density come from the Dataverse source and are NA where it has no
match.
Jolad, Shivakumar and Singh, Madhav (2026). "Indian Census Data Collection, 1901-2026: Digitised Subnational Population and Administrative Datasets." Harvard Dataverse. doi:10.7910/DVN/ON8CP8.
Available census variables with labels, years, geographic levels, and categories.
census_variablescensus_variables
A tibble with 23 rows and 5 columns:
Variable name used in package functions
Human-readable label
Comma-separated list of available years
Comma-separated list of available geographic levels
Variable category (population, literacy, workers, etc.)
census_population_time_series carries rows for 1900, 1910, 1940, 1948,
1950, 1960, 1962 and 2021 alongside the twelve decennial censuses. A
lag() over the unfiltered table silently produces one- and thirteen-year
intervals labelled as decadal.
census_years(data)census_years(data)
data |
A frame with a |
data keeping only the twelve census years, 1901 to 2011.
census_population_time_series |> census_years() |> dplyr::distinct(year)census_population_time_series |> census_years() |> dplyr::distinct(year)
Releases the boundaries and downloaded tables held in memory for the session.
clear_geometry_cache()clear_geometry_cache()
Invisible NULL
clear_census_cache() to delete downloaded files from disk.
clear_geometry_cache()clear_geometry_cache()
Compare maps across years
compare_maps( data_list, fill_var, title = NULL, ncol = NULL, palette = "viridis", common_scale = TRUE, show_state_boundaries = TRUE, ... )compare_maps( data_list, fill_var, title = NULL, ncol = NULL, palette = "viridis", common_scale = TRUE, show_state_boundaries = TRUE, ... )
data_list |
A named list of sf data frames, with names as years |
fill_var |
The variable to map (string) |
title |
Overall title for the combined plot |
ncol |
Number of columns for arrangement |
palette |
Color palette (see |
common_scale |
Logical. Use the same color scale across all maps? |
show_state_boundaries |
Logical. Overlay state boundaries? |
... |
Additional arguments passed to |
A patchwork object
# Compare ST percentage across years library(dplyr) st_1971 <- census_1971 |> filter(geography == "district") |> mutate(st_pct = 100 * st_population_total / population_total) |> attach_geometry(1971) st_2011 <- census_2011_pca |> mutate(st_pct = 100 * st_population / population_total) |> attach_geometry(2011) # Compare compare_maps( list("1971" = st_1971, "2011" = st_2011), fill_var = "st_pct", title = "ST Population % by District", palette = "red_blue" )# Compare ST percentage across years library(dplyr) st_1971 <- census_1971 |> filter(geography == "district") |> mutate(st_pct = 100 * st_population_total / population_total) |> attach_geometry(1971) st_2011 <- census_2011_pca |> mutate(st_pct = 100 * st_population / population_total) |> attach_geometry(2011) # Compare compare_maps( list("1971" = st_1971, "2011" = st_2011), fill_var = "st_pct", title = "ST Population % by District", palette = "red_blue" )
Census data for India at state, district, or subdistrict level.
get_census( year, geography = c("state", "district", "subdistrict"), variables = NULL, state = NULL, geometry = FALSE, sector = c("total", "rural", "urban") )get_census( year, geography = c("state", "district", "subdistrict"), variables = NULL, state = NULL, geometry = FALSE, sector = c("total", "rural", "urban") )
year |
Census year. One of: 1901, 1911, 1921, 1931, 1941, 1951, 1961, 1971, 1981, 1991, 2001, 2011. |
geography |
Geographic level: "state", "district", or "subdistrict". Not all geographies are available for all years. |
variables |
Character vector of variables to retrieve. Use
|
state |
Optional. Filter to specific state(s). Can be state name or abbreviation (e.g., "Maharashtra" or "MH"). |
geometry |
If TRUE, returns an sf object with geographic boundaries. |
sector |
For 1971/1981, filter to "total", "rural", or "urban". Other years have no sector split, so "rural" or "urban" is an error there. |
A tibble (or sf object if geometry = TRUE).
get_census(2011, "state") get_census(1971, "district", state = "Maharashtra") get_census(1981, "district", variables = c("population", "literacy_rate"), geometry = TRUE)get_census(2011, "state") get_census(1971, "district", state = "Maharashtra") get_census(1981, "district", variables = c("population", "literacy_rate"), geometry = TRUE)
State or district boundaries for a given census year.
get_census_boundaries(year, geography = c("state", "district"))get_census_boundaries(year, geography = c("state", "district"))
year |
Census year. Available: 1941, 1951, 1961, 1971, 1981, 1991, 2001, 2011. |
geography |
Geographic level: "state" or "district". |
An sf object containing the geographic boundaries with harmonized state names.
Boundary files are downloaded on first use; see census_cache_dir().
boundaries <- get_census_boundaries(1971, "district") ggplot2::ggplot(boundaries) + ggplot2::geom_sf()boundaries <- get_census_boundaries(1971, "district") ggplot2::ggplot(boundaries) + ggplot2::geom_sf()
Get color palettes for maps. Available palettes: "viridis", "red_blue", "blue_red", "greens", "oranges", "reds", "blues", "purple_green".
get_palette(name, reverse = FALSE)get_palette(name, reverse = FALSE)
name |
Name of the palette |
reverse |
Logical. Reverse direction? |
A character vector of colors
get_palette("blues") get_palette("red_blue", reverse = TRUE)get_palette("blues") get_palette("red_blue", reverse = TRUE)
MOHFW population projections (2011-2036) at state or district level, based on the 2011 Census. District projections are available using either Census 2011 boundaries (640 districts, 5-year intervals) or current LGD boundaries (785 districts, annual).
get_population( year = NULL, geography = c("state", "district"), state = NULL, boundary = c("census2011", "lgd"), geometry = FALSE, by_age = FALSE )get_population( year = NULL, geography = c("state", "district"), state = NULL, boundary = c("census2011", "lgd"), geometry = FALSE, by_age = FALSE )
year |
Integer or integer vector of projection years. If NULL (default), returns all available years. |
geography |
Geographic level: |
state |
Optional. Filter to specific state(s) by name or
abbreviation (e.g., |
boundary |
For district geography, which boundary system:
|
geometry |
If |
by_age |
If |
State-level data covers 2011-2036 for 38 entries (36 states/UTs plus India total plus Ladakh). Values are in persons, including the state rows by age, which population_projections_state_age stores in thousands.
The source data rounds Persons, Male, and Female independently (in
thousands), so population may differ from males + females by up
to 1000 at the state level.
District-level Census 2011 data has projections at 5-year intervals (2011, 2016, 2021, 2026, 2031). LGD district data has annual projections from 2012 to 2031.
A year absent from the table is estimated from the two nearest table
years by geometric (exponential) growth, applied separately to males,
females and population:
Estimated districts need not sum exactly to the estimated state.
Years after the last table year extrapolate with the last interval's rate, up to five years out: 2041 for states, 2036 for districts. Years before 2011 or past that limit are an error.
Telangana and Ladakh are included as separate entries even though they did not exist as states at the time of the 2011 Census.
A tibble (or sf object if geometry = TRUE) with columns:
year, state_name_harmonized, males, females, population,
estimate, district for district-level data, and age_group if
by_age = TRUE. estimate is "published" for a year printed in the
MOHFW tables, "interpolated" or "extrapolated" otherwise.
# State-level projections for 2021 get_population(2021, "state") # District-level for Kerala get_population(2021, "district", state = "Kerala") # LGD boundary districts get_population(2021, "district", boundary = "lgd") # Age-stratified state projections get_population(2021, "state", by_age = TRUE)# State-level projections for 2021 get_population(2021, "state") # District-level for Kerala get_population(2021, "district", state = "Kerala") # LGD boundary districts get_population(2021, "district", boundary = "lgd") # Age-stratified state projections get_population(2021, "state", by_age = TRUE)
States and union territories with codes, abbreviations, and regions.
india_statesindia_states
A tibble with 36 rows and 5 columns:
Numeric state code (Census 2011 codes)
Official state name
Harmonized state name for joining across datasets
Two-letter state abbreviation
Geographic region (North, South, East, West, Central, Northeast, Islands)
Geographic levels available for each census year.
list_census_geographies()list_census_geographies()
A tibble showing available year-geography combinations.
list_census_geographies()list_census_geographies()
Available census variables, optionally filtered by year, geography, or category.
list_census_variables(year = NULL, geography = NULL, category = NULL)list_census_variables(year = NULL, geography = NULL, category = NULL)
year |
Filter to variables available for specific census year. |
geography |
Filter to "state", "district", or "subdistrict". |
category |
Filter to "population", "literacy", "workers", "sc_st", "housing", "geography", or "change". |
A tibble of available variables.
list_census_variables() list_census_variables(year = 1981) list_census_variables(category = "literacy", geography = "district")list_census_variables() list_census_variables(year = 1981) list_census_variables(category = "literacy", geography = "district")
States and union territories with codes, abbreviations, and regions.
list_states(region = NULL)list_states(region = NULL)
region |
Filter by region: "North", "South", "East", "West", "Central", "Northeast", "Islands". |
A tibble of states with codes, names, abbreviations, and regions.
list_states() list_states(region = "South")list_states() list_states(region = "South")
Create a choropleth map from census data.
plot_map( data, fill_var, title = NULL, subtitle = NULL, legend_title = NULL, palette = "viridis", reverse = FALSE, direction = NULL, na_color = "grey80", boundary_year = NULL, base_layer = TRUE, show_state_boundaries = FALSE, state_boundary_color = "black", state_boundary_width = 0.3, trans = "identity", midpoint = NULL, oob = NULL, limits = NULL, breaks = NULL, labels = NULL, font_family = NULL, legend_position = "right" )plot_map( data, fill_var, title = NULL, subtitle = NULL, legend_title = NULL, palette = "viridis", reverse = FALSE, direction = NULL, na_color = "grey80", boundary_year = NULL, base_layer = TRUE, show_state_boundaries = FALSE, state_boundary_color = "black", state_boundary_width = 0.3, trans = "identity", midpoint = NULL, oob = NULL, limits = NULL, breaks = NULL, labels = NULL, font_family = NULL, legend_position = "right" )
data |
An sf object or data frame with geometry attached via
|
fill_var |
The variable to map to fill color (unquoted or string) |
title |
Optional title for the map |
subtitle |
Optional subtitle for the map |
legend_title |
Title for the legend |
palette |
Color palette. Options include:
|
reverse |
Logical. Reverse the color palette direction? Default FALSE. |
direction |
Numeric. Alternative to reverse: use -1 to reverse, 1 for default. If both reverse and direction are specified, direction takes precedence. |
na_color |
Color for missing values. Default is "grey80" |
boundary_year |
Census year whose state boundaries to draw beneath the
data, keeping India's full claimed extent on the map even where the census
enumerates no districts. Defaults to the |
base_layer |
Logical. Draw India's full state outline beneath the data? Default TRUE |
show_state_boundaries |
Logical. Overlay state boundaries? |
state_boundary_color |
Color for state boundaries. Default is "black" |
state_boundary_width |
Width of state boundary lines. Default is 0.3 |
trans |
Transformation for the color scale (e.g., "log10", "sqrt"). Default is "identity" (no transformation) |
midpoint |
Value to centre a diverging palette on, e.g. |
oob |
How to treat values outside |
limits |
Optional limits for the color scale as c(min, max) |
breaks |
Optional breaks for the legend |
labels |
Optional labels for the legend breaks |
font_family |
Font family for all map text. Default |
legend_position |
One of |
A ggplot2 object
# Calculate ST percentage and attach geometry st_data <- census_2011_pca |> dplyr::mutate(st_pct = 100 * st_population / population_total) |> attach_geometry(2011) # Create a basic map plot_map(st_data, st_pct, title = "ST Population %") # With red-blue palette and state boundaries plot_map(st_data, st_pct, title = "ST Population % (2011)", palette = "red_blue", show_state_boundaries = TRUE )# Calculate ST percentage and attach geometry st_data <- census_2011_pca |> dplyr::mutate(st_pct = 100 * st_population / population_total) |> attach_geometry(2011) # Create a basic map plot_map(st_data, st_pct, title = "ST Population %") # With red-blue palette and state boundaries plot_map(st_data, st_pct, title = "ST Population % (2011)", palette = "red_blue", show_state_boundaries = TRUE )
Choropleth maps and comparison plots from census data.
MOHFW population projections at district level using Census 2011 boundaries (640 districts). Projections are at 5-year intervals: 2011, 2016, 2021, 2026, 2031. Values match the IIPS report's Table 8.
population_projections_districtpopulation_projections_district
A tibble with 3,200 rows and 6 columns:
Projection year (5-year intervals)
Harmonized state name for joining
District name (MOHFW naming convention)
Projected male population
Projected female population
Projected total population (males + females)
The report's age tables (population_projections_district_age()) sum
to different totals for Karnataka in 2016-2031 and for Uttar Pradesh and
Nagaland in 2016.
Compatible with attach_geometry() using 2011 district boundaries.
International Institute for Population Sciences. Projection of District Level Annual Population by Quinquennial Agegroup and Sex. https://www.iipsindia.ac.in/sites/default/files/1_3.pdf
Age-stratified detail behind population_projections_district, on Census
2011 district boundaries (no LGD spatial apportionment involved). Same
age-group scheme as population_projections_district_lgd_age(): single
years 0-14, then 5-year bands through 80+. Downloaded on first use;
see census_cache_dir().
population_projections_district_age()population_projections_district_age()
Values are as printed in the IIPS report. District names match population_projections_district.
Two blocks are derived because the PDF does not print them. Moga (Punjab) and Tapi (Gujarat) print no 80+ row for 2022-2026; it is the printed All ages minus the other printed age groups. Theni's (Tamil Nadu) 2017-2031 pages repeat Madurai's numbers; Karnataka's age tables sum to a different projection from population_projections_district.
A tibble with 371,200 rows and 7 columns:
Projection year (annual, 2012-2031)
Harmonized state name for joining
District name (Census 2011 naming convention)
Single years "0".."14", then 5-year bands "15-19" through "80+"
Projected male population
Projected female population
Projected total population (males + females)
Same as population_projections_district.
population_projections_district_age() |> head()population_projections_district_age() |> head()
MOHFW population projections scaled to current Local Government
Directory (LGD) district boundaries. Annual projections from 2012 to
2031, summed across age groups from population_projections_district_lgd_age().
population_projections_district_lgdpopulation_projections_district_lgd
A tibble with 15,660 rows and 6 columns:
Projection year (annual, 2012-2031)
Harmonized state name for joining. Dadra & Nagar Haveli and Daman & Diu appear merged as one UT (their 2020 administrative merger); the LGD source has no district-level way to split them back apart.
District name (LGD naming convention)
Projected male population
Projected female population
Projected total population (males + females)
Derived from population_projections_district_age() by area overlap, so
district sums do not exactly reproduce population_projections_state,
and Karnataka inherits the age tables' disagreement with
population_projections_district.
Theni (Tamil Nadu) 2017-2031 and the 80+ group of Moga (Punjab) and Tapi
(Gujarat) in 2022-2026 are derived, as in
population_projections_district_age().
International Institute for Population Sciences. Projection of District Level Annual Population by Quinquennial Agegroup and Sex. https://www.iipsindia.ac.in/sites/default/files/1_3.pdf District scaling from Census 2011 to LGD boundaries via spatial overlap analysis.
Age-stratified detail behind population_projections_district_lgd: single
years of age for 0-14, five-year bands from 15-19 through 80+. Fixes the
same double-counted "All ages" row bug documented on that table. Downloaded
on first use; see census_cache_dir().
population_projections_district_lgd_age()population_projections_district_lgd_age()
A tibble with 454,140 rows and 7 columns:
Projection year (annual, 2012-2031)
Harmonized state name for joining. See population_projections_district_lgd for the Dadra & Nagar Haveli / Daman & Diu merged-UT caveat.
District name (LGD naming convention)
Single years "0".."14", then 5-year bands "15-19" through "80+". Non-overlapping: summing all rows for a district-year reproduces population_projections_district_lgd.
Projected male population
Projected female population
Projected total population (males + females)
Same as population_projections_district_lgd.
population_projections_district_lgd_age() |> head()population_projections_district_lgd_age() |> head()
MOHFW population projections at state level, based on the 2011 Census.
Covers 38 entries (36 states/UTs, India total, and Ladakh) with annual
projections from 2011 to 2036. Values are absolute numbers (the source
rounds in thousands independently, so population may differ from
males + females by up to 1000).
population_projections_statepopulation_projections_state
A tibble with 988 rows and 5 columns:
Projection year (2011-2036)
Harmonized state name for joining
Projected male population
Projected female population
Projected total population
Values match the report's Table 8. India and Odisha follow the July 2020 edition, which revised Odisha's male projection, so both rows differ from the November 2019 print linked below.
Ministry of Health and Family Welfare, Government of India. Population Projections for India and States 2011-2036. https://nhm.gov.in/New_Updates_2018/Report_Population_Projection_2019.pdf
Age-stratified population reshaped directly from the MOHFW report's own Table 18, wide-by-year to tidy long. Summing to state-year reproduces population_projections_state to within report rounding (Uttar Pradesh 2016: 216,089 vs 216,087 thousand).
population_projections_state_agepopulation_projections_state_age
A tibble with 2,448 rows and 5 columns:
Projection year (2011-2036, at 5-year intervals: 2011, 2016, 2021, 2026, 2031, 2036)
Harmonized state name for joining where the report breaks the state out individually; "India" and "North East States Excluding Assam" pass through verbatim as aggregate rows
Five-year bands "0-4" through "80+"
Projected male population, in thousands
Projected female population, in thousands
Projected total population (the printed Person figure), in thousands
Values match the printed Table 18.
population is the printed Person figure, rounded separately from
males and females, so it can differ from their sum by 1. India and
Odisha follow the July 2020 edition, as in population_projections_state,
and there population is males + females.
Coverage is narrower than population_projections_state: the report only breaks out 23 major states individually plus an "India" total, lumping the smaller North East states (Sikkim, Arunachal Pradesh, Nagaland, Manipur, Mizoram, Tripura, Meghalaya) into one "North East States Excluding Assam" row. Chandigarh, small UTs and Ladakh are not in this table at all.
Ministry of Health and Family Welfare, Government of India. Population Projections for India and States 2011-2036, Table 18. https://nhm.gov.in/New_Updates_2018/Report_Population_Projection_2019.pdf
Find census variables by keyword in names and labels.
search_census_variables(pattern)search_census_variables(pattern)
pattern |
Character string or regex pattern to search. |
A tibble of matching variables.
search_census_variables("population") search_census_variables("worker")search_census_variables("population") search_census_variables("worker")
Launches the bundled plumber API on the given host and port. Every
endpoint takes GET query parameters that mirror the R function behind it,
with comma-separated values for vectors (state=KL,TN):
serve(host = "127.0.0.1", port = 8895L, ...) census_api(host = "127.0.0.1", port = 8895L, ...)serve(host = "127.0.0.1", port = 8895L, ...) census_api(host = "127.0.0.1", port = 8895L, ...)
host |
Host address to bind. Default |
port |
Port number. Default |
... |
Additional arguments passed to |
| Endpoint | Function |
/query |
get_census() |
/population |
get_population() |
/boundaries |
get_census_boundaries() |
/languages |
census_languages() |
/sc-st |
census_sc_st() |
/datasets, /dataset/<name> |
any shipped dataset, e.g. census_1931_castes |
/variables, /search |
list_census_variables(), search_census_variables() |
/states, /geographies |
list_states(), list_census_geographies() |
/health |
package version |
Results come back as JSON rows, or as a GeoJSON FeatureCollection when
geometry=true and from /boundaries. Input the R function rejects is a
400 carrying its error message, and a failed data download is a 503.
Interactive documentation is served at /__docs__/.
A response holds at most 10,000 rows, or 100 features for GeoJSON. Page
through larger results with limit and offset; the X-Total-Count header
gives the full count.
Each request writes one JSON line to standard output with its path, query,
status, duration, client IP and a client label. The label comes from an
X-Client header when one is sent (an MCP server wrapping the API should
send X-Client: mcp/<name>), and otherwise from the User-Agent: mcp,
ai_agent, curl, wget, python, r, node, browser, other or
unknown. Under systemd these lines land in the journal.
Called for its side effect; does not return under normal operation.
# Start locally on the default port serve() # Bind to all interfaces on a custom port serve(host = "0.0.0.0", port = 9000)# Start locally on the default port serve() # Bind to all interfaces on a custom port serve(host = "0.0.0.0", port = 9000)
Females per 1,000 males, the convention the Census of India reports.
sex_ratio(females, males)sex_ratio(females, males)
females, males
|
Counts, of equal length. |
Numeric vector.
sex_ratio(census_2011_pca$population_female, census_2011_pca$population_male) |> head()sex_ratio(census_2011_pca$population_female, census_2011_pca$population_male) |> head()
theme_census() for plots with axes, theme_census_map() for choropleths.
theme_census(base_size = 11) theme_census_map(base_size = 11)theme_census(base_size = 11) theme_census_map(base_size = 11)
base_size |
Base font size in points. |
A ggplot2 theme.
ggplot2::ggplot(census_2011_pca, ggplot2::aes(literate_total, population_total)) + ggplot2::geom_point() + theme_census()ggplot2::ggplot(census_2011_pca, ggplot2::aes(literate_total, population_total)) + ggplot2::geom_point() + theme_census()