Documentation
> Workflows & Code
> Explore Metadata
> IHGIS
Explore IPUMS IHGIS Metadata
Below we provide examples in curl showing how to work with our API to explore IHGIS metadata.
If you are an R or Python user, please note that we also provide language-native client libraries to make it easier to work with the IPUMS API using those languages.
Get your key from https://account.ipums.org/api_keys. Make sure to replace 'MY_KEY' (all caps) in the snippet below with your key.
Load Libraries and Set Key
export KEY=MY_KEY # set the MY_KEY environment variable using bash shellDatasets
Each IHGIS dataset contains tables based on a census conducted in a particular country in a particular year. Datasets that end with ‘pop’ are from population or population and housing censuses, and consist of tables published by the national statistical office (NSO). Datasets that end with ‘ag’ consist of published tables from agricultural censuses. Datasets that end with ‘tab’ are tabulated from IPUMS International microdata samples. An overview of IHGIS datasets and listing of NSO sources are available on the IHGIS website.
Get All Datasets
This API call will return a list of all available datasets. The unique identifier for each dataset is in the name field. This is needed for retrieving details about a single dataset (see next section).
curl -X GET \
"https://api.ipums.org/metadata/datasets?collection=ihgis&version=2" \
-H "Authorization: $MY_KEY" | jq
# Results
{
"data": [
{
"name": "AL2001pop",
"description": "Population and Housing Census 2001",
"datasetType": "Population Census",
"country": "AL",
"countryLabel": "Albania",
"year": "2001",
"statisticalAgency": "Institute of Statistics (INSTAT)",
"universe": "Usual residents of Albania as of midnight October 1st, 2011",
"deJureDeFacto": "de jure",
"enumerationUnit": "Housing unit, household, and population ",
"referencePeriod": "Census date: April 1, 2001",
"fieldworkPeriod": "Interviews take place on the expected census day in each state.",
"fieldworkType": "Direct enumeration via house-to-house visits and personal interviews conducted by pre-trained census enumerators",
"enumerationForms": "Individual, household, and dwelling (building and dwelling) forms. The forms are called Enumerator Summary Lists",
"coverage": "n/a",
"sample": "n/a",
"dwellingDefinition": "Dwellings can be conventional dwellings or non-conventional dwellings. A conventional dwelling is an independent room/suite of rooms and its accessories in a permanent building or structurally separated part thereof, designed for year round habitation, e.g. houses, apartments. A non-conventional dwelling is semi-permanent or improvised or is not designed for permanent human habitation, but is nevertheless being used at the time of census as the usual residence of one or more persons.",
"householdDefinition": "A household is a group of persons residing together in a housing unit sharing a partially or fully joint economy. Households may consist of a single-person or multiple persons who may or may not be related and/or have familial bonds.",
"groupQuartersDefinition": "Collective living quarters are premises which are designed for habitation by large groups of individuals and which, generally, are used as the usual residence of at least one person at the time of the census. The persons that live in collective living quarters are subject to a common authority or regime or bound by a common objective or personal interest together for purposes of schooling, health, criminal conviction, welfare, etc. [based on documentation for 2011 census]",
"sequence": 1,
"dataTableCount": 114
},
{
"name": "AL2012ag",
"description": "Preliminary Results of Agriculture Census, 2012",
"datasetType": "Agricultural Census",
"country": "AL",
"countryLabel": "Albania",
"year": "2012",
"statisticalAgency": "Institute of Statistics of Albania (INSTAT)",
"universe": "All agricultural units within the enumeration areas.",
"deJureDeFacto": "n/a",
"enumerationUnit": "Agricultural holding",
"referencePeriod": "Census date: October 1, 2012 for inventory items, such as livestock numbers and farm buidings; Census dates: October 1, 2011 to September 30, 2012 for land use, agricultural production methods, machinery used, other gainful activities, labor force, sales of production, credit and insurance, etc.; the 12 months preceding the interview for animal grazing, training fo the farm manager, main location of livestock",
"fieldworkPeriod": "October 1 - 31, 2012",
"fieldworkType": "Two-step data collection: 1) door-to-door contact with face-to-face interviews and 2) Post-enumeration survey questionnaire.",
"enumerationForms": "One detailed census questionnaire, covering all 16 core items recommended in the World Census of Agriculture 2010.",
"coverage": "Post-enumeration survey indicated an undercoverage rate of 7.6%.",
"sample": "Complete enumeration; frame established based on data from (i) Census of Population and Housing regarding households involved in agricultural activities; (ii) data provided from the Farm Identification Campaign 2011; (iii) INSTAT Business Register; (iv) list of public and religious bodies, etc.",
"dwellingDefinition": "n/a",
"householdDefinition": "Agricultural holding - A single unit, both technically and economically, which has a single management, is composed of land even in fragmented parcels, and undertakes agricultural and livestock activities within the economic territory of Albania.",
"groupQuartersDefinition": "n/a",
"sequence": 2,
"dataTableCount": 5
},
[SNIP]
{
"name": "ZM2010tab",
"description": "2010 Census of Population and Housing",
"datasetType": "Tabulated from IPUMS International Microdata Sample",
"country": "ZM",
"countryLabel": "Zambia",
"year": "2010",
"statisticalAgency": "Central Statistical Office",
"universe": "n/a",
"deJureDeFacto": "De jure and de facto",
"enumerationUnit": "Population, households, dwellings",
"referencePeriod": "Census date: October 15, 2010",
"fieldworkPeriod": "October 17, 2010 - November 15, 2010. For very remote areas data collection continued until the end of November.",
"fieldworkType": "Direct enumeration",
"enumerationForms": "A single enumeration form requested information on the dwelling, household, and individuals.",
"coverage": "n/a",
"sample": "10 percent sample drawn by Central Statistical Office with Technical support from the US Census Bureau from 100 % Microdata -- Sample fraction: 10% -- Sample size: 1,321,973 persons",
"dwellingDefinition": "An independent place of abode intended for habitation by one household.",
"householdDefinition": "A group of persons who normally live and eat together. These people may or may not be related by blood, but make common provision for food or other essentials for living and they have only one person whom they all regard as head of the household. Such people are called members of the household if they normally live and eat together even if they do not sleep under one roof. There can also be a one member household where a person makes provision for his/her own food or other essentials for living. Such a person is the head of his/her household.",
"groupQuartersDefinition": "n/a",
"sequence": 364,
"dataTableCount": 58
},
{
"name": "ZW2012tab",
"description": "Population Census 2012",
"datasetType": "Tabulated from IPUMS International Microdata Sample",
"country": "ZW",
"countryLabel": "Zimbabwe",
"year": "2012",
"statisticalAgency": "National Statistical Agency",
"universe": "All persons present in the country on census day",
"deJureDeFacto": "De facto",
"enumerationUnit": "Population, households",
"referencePeriod": "Census date: August 17, 2012",
"fieldworkPeriod": "n/a",
"fieldworkType": "Direct enumeration",
"enumerationForms": "A single census form for dwellings and persons",
"coverage": "n/a",
"sample": "5% sample drawn by national statistics office -- Sample fraction: 5% -- Sample size: 654,688 persons",
"dwellingDefinition": "n/a",
"householdDefinition": "A household is defined as person or a group of persons who stayed the census night in the dwelling unit, whether or not they were related by blood or marriage, including visitors.",
"groupQuartersDefinition": "Collective households are formed where institutionalized populations are found e.g. hospitals, hostels, hotels, prisons, military barracks, refugee camps, schools, colleges, old people's homes, orphanage, etc.",
"sequence": 365,
"dataTableCount": 38
}
],
"pageNumber": 1,
"pageSize": 500,
"totalCount": 356,
"links": {
"previousPage": null,
"nextPage": null
}
}Note that this is a paginated endpoint. The default page size is 500 items. If there were more than 500 items, or if the pageSize parameter were set to less than the total dataset count in this example, the links->nextPage field would have a URL to retrieve the next page of results.
Get Detailed Metadata for a Single Dataset
This API call will return the details of a single dataset, AL2001pop in this example. The details include the data tables and tabulation geographies available for the dataset.
curl -X GET \
"https://api.ipums.org/metadata/datasets/AL2001pop?collection=ihgis&version=2" \
-H "Authorization: $MY_KEY" | jq
# Results
{
"name": "AL2001pop",
"description": "Population and Housing Census 2001",
"datasetType": "Population Census",
"country": "AL",
"countryLabel": "Albania",
"year": "2001",
"statisticalAgency": "Institute of Statistics (INSTAT)",
"universe": "Usual residents of Albania as of midnight October 1st, 2011",
"deJureDeFacto": "de jure",
"enumerationUnit": "Housing unit, household, and population ",
"referencePeriod": "Census date: April 1, 2001",
"fieldworkPeriod": "Interviews take place on the expected census day in each state.",
"fieldworkType": "Direct enumeration via house-to-house visits and personal interviews conducted by pre-trained census enumerators",
"enumerationForms": "Individual, household, and dwelling (building and dwelling) forms. The forms are called Enumerator Summary Lists",
"coverage": "n/a",
"sample": "n/a",
"dwellingDefinition": "Dwellings can be conventional dwellings or non-conventional dwellings. A conventional dwelling is an independent room/suite of rooms and its accessories in a permanent building or structurally separated part thereof, designed for year round habitation, e.g. houses, apartments. A non-conventional dwelling is semi-permanent or improvised or is not designed for permanent human habitation, but is nevertheless being used at the time of census as the usual residence of one or more persons.",
"householdDefinition": "A household is a group of persons residing together in a housing unit sharing a partially or fully joint economy. Households may consist of a single-person or multiple persons who may or may not be related and/or have familial bonds.",
"groupQuartersDefinition": "Collective living quarters are premises which are designed for habitation by large groups of individuals and which, generally, are used as the usual residence of at least one person at the time of the census. The persons that live in collective living quarters are subject to a common authority or regime or bound by a common objective or personal interest together for purposes of schooling, health, criminal conviction, welfare, etc. [based on documentation for 2011 census]",
"sequence": 1,
"dataTableCount": 114,
"dataTables": [
{
"name": "AL2001pop.AAA",
"datasetName": "AL2001pop",
"label": "Resident Population and Households",
"universe": "Varies",
"tableNum": "1.1",
"sequence": 1,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": [
"IPUMS: Old age index = (P 65+ / P 0-15 x 100), Dependence index = ((P>15 + P+ 64) / P 15-65 x 100), Substitution index = (P 60-64 / P 15-19 x 100)"
]
},
{
"name": "AL2001pop.AAB",
"datasetName": "AL2001pop",
"label": "Education",
"universe": "Resident population 6 years and over",
"tableNum": "1.2",
"sequence": 2,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAC",
"datasetName": "AL2001pop",
"label": "Labor",
"universe": "Resident population 15 years old and over",
"tableNum": "1.3",
"sequence": 3,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAD",
"datasetName": "AL2001pop",
"label": "Buildings and Dwellings",
"universe": "Varies",
"tableNum": "1.4",
"sequence": 4,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAE",
"datasetName": "AL2001pop",
"label": "Resident Population by Sex, Marital Status, and Age Group (Urban and Rural Zones)",
"universe": "Resident population",
"tableNum": "2.1",
"sequence": 5,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAF",
"datasetName": "AL2001pop",
"label": "Resident Population by Educational Attainment, Age Group, and Sex (Urban and Rural Zones)",
"universe": "Resident population 6 years and over",
"tableNum": "2.2",
"sequence": 6,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAG",
"datasetName": "AL2001pop",
"label": "Resident Population by Current Activity Status, Sex, and Age Group (Urban and Rural Zones)",
"universe": "Resident population 15 years old and over",
"tableNum": "2.3",
"sequence": 7,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAH",
"datasetName": "AL2001pop",
"label": "Resident Population by Educational Attainment, Activity Status, Age Group, and Sex (Urban and Rural Zones)",
"universe": "Resident population 15 years old and over",
"tableNum": "2.4",
"sequence": 8,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAI",
"datasetName": "AL2001pop",
"label": "Resident Population Employed by Educational Attainment, Branch of Economic Activity, Age Group, and Sex (Urban and Rural Zones)",
"universe": "Employed resident population",
"tableNum": "2.5",
"sequence": 9,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAJ",
"datasetName": "AL2001pop",
"label": "Resident Population Employed by Educational Attainment, Status Employement, Sex (Urban and Rural Zones)",
"universe": "Employed resident population",
"tableNum": "2.6",
"sequence": 10,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAK",
"datasetName": "AL2001pop",
"label": "Resident Population Employed by Educational Attainment, Type of Work, and Sex (Urban and Rural Zones)",
"universe": "Employed resident population",
"tableNum": "2.7",
"sequence": 11,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAL",
"datasetName": "AL2001pop",
"label": "Resident Population Employed by Age Group, Branch of Economic Activity and Sex (Urban and Rural Zones)",
"universe": "Employed resident population",
"tableNum": "2.8",
"sequence": 12,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAM",
"datasetName": "AL2001pop",
"label": "Resident Population Employed by Age Group, Occupation and Sex",
"universe": "Employed resident population",
"tableNum": "2.9",
"sequence": 13,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAN",
"datasetName": "AL2001pop",
"label": "Resident Population Employed by Number of Hours Worked in a Week, Branch of Economic Activities, and Sex (Urban and Rural Zones)",
"universe": "Employed resident population",
"tableNum": "2.10",
"sequence": 14,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAO",
"datasetName": "AL2001pop",
"label": "Resident Population by Number of Hours Worked (in Paid Employment) in the Last Week, Economic Status, and Sex (Urban and Rural Zones)",
"universe": "IPUMS: Resident population aged 15 years and above",
"tableNum": "2.11",
"sequence": 15,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAP",
"datasetName": "AL2001pop",
"label": "Resident Population Employed by Number of Hours Usually Worked in a Week, Economic Status, and Sex (Urban and Rural Zones)",
"universe": "Employed resident population",
"tableNum": "2.12",
"sequence": 16,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAQ",
"datasetName": "AL2001pop",
"label": "Resident Population by Economic Status, Mean of Transport Most Used, and Sex (Urban and Rural Zones)",
"universe": "Resident population 15 years old and over",
"tableNum": "2.13",
"sequence": 17,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAR",
"datasetName": "AL2001pop",
"label": "Resident Employed Population by Type of Job, Place of Work and Sex",
"universe": "Employed resident population",
"tableNum": "2.14",
"sequence": 18,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAS",
"datasetName": "AL2001pop",
"label": "Resident Employed Population Not Working from Home by Type of Return from Work to Permanent Residence, Place of Work, and Sex",
"universe": "Employed resident population not working from home",
"tableNum": "2.15",
"sequence": 19,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAT",
"datasetName": "AL2001pop",
"label": "Resident Population by Age Group, Place of Birth and Sex",
"universe": "Resident population",
"tableNum": "2.16",
"sequence": 20,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAU",
"datasetName": "AL2001pop",
"label": "Resident Population by Age Group, Place of Residence on 1 April 1989, and Sex",
"universe": "Resident population",
"tableNum": "2.17",
"sequence": 21,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAV",
"datasetName": "AL2001pop",
"label": "Resident Population by Age Group, Place of Residence on 1 April 2000, and Sex",
"universe": "Resident population",
"tableNum": "2.18",
"sequence": 22,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAW",
"datasetName": "AL2001pop",
"label": "Women by Age Group and by Number of Children Born",
"universe": "IPUMS: Female resident population aged 15 years and above reporting number of children",
"tableNum": "2.19",
"sequence": 23,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAX",
"datasetName": "AL2001pop",
"label": "Women by Number of Children Still Alive at 1 April 2001, by Age Group (Urban and Rural Zones)",
"universe": "IPUMS: Female resident population aged 15 years and above reporting at least one child ever born",
"tableNum": "2.20",
"sequence": 24,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
},
{
"name": "AL2001pop.AAY",
"datasetName": "AL2001pop",
"label": "Households by Number of Members and by Type of Household",
"universe": "Varies",
"tableNum": "2.21",
"sequence": 25,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": []
}
],
"tabulationGeographies": [
{
"name": "AL2001pop.g0",
"label": "Nation",
"hierarchicalLevel": "g0",
"meanPopulation": 3069275,
"meanArea": 28671.4,
"sequence": 1,
"unitCount": 1
},
{
"name": "AL2001pop.g1",
"label": "Prefectures",
"hierarchicalLevel": "g1",
"meanPopulation": 85258,
"meanArea": 796.4,
"sequence": 2,
"unitCount": 36
}
]
}Dataset Attributes
name: The unique identifier of the dataset.description: The title of the census.datasetType: The type of dataset (population, agricultural, or tabulated).country: A two-character abbreviation of the country.countryLabel: The name of the country.year: The year the census was conducted.statisticalAgency: The name of the statistical agency that conducted the census.universe: A description of the population that was included in the enumeration, often describing any categories of people who were not counted.deJureDeFacto: Indicates whether the census counted people who reside in the country (including those who were absent on the census day) [de jure], or people who were present in the country on the census day (including visitors) [de facto].enumerationUnit: The types of entities counted in the census. May include population, households, dwelling units, etc. for population censuses; and population, households, farms, plots, etc. for agricultural censuses.referencePeriod: The date of record. People who were residents of or present in the country as of this date were counted.fieldworkPeriod: The time period during which enumeration took place.fieldworkType: The methods used for enumeration, such as face-to-face interviews or online forms.enumerationForms: The type of enumeration forms used to collect information.coverage: If available, an estimate of how complete the enumeration was.sample: If applicable, the proportion of the population included in the sample on which the data tables are based. Applies primarily to datasets tabulated from IPUMS International samples and some agricultural datasets that were not complete enumerations.dwellingDefinition: The definition used by the census of what constitutes a distinct dwelling unit.householdDefinition: The definition used by the census of how people are grouped into households.groupQuartersDefinition: The definition used by the census of what constitutes group quarters. People categorized as living in group quarters are generally not considered to live in households.sequence: The order in which the dataset will appear in the metadata API and extract metadata.dataTableCount: The number of data tables included in the dataset.dataTables: A list of data tables available for this dataset.tabulationGeographies: A list of tabulation geographies available for this dataset.
Data Tables
Data tables are the primary unit of information in IHGIS. For datasets based on published census results, table composition generally follows the published tables. For datasets tabulated from IPUMS International, a standard set of tabulations is calculated from each sample (subject to availability of the necessary variables in the microdata).
Get All Data Tables
This API call will return a list of all available data tables. The results from this endpoint can be filtered to list tables across related datasets or for finding data tables containing specific keywords in their label. The unique identifier for each dataset is in the name field. This is needed for retrieving details about a single data table (see next section).
curl -X GET \
"https://api.ipums.org/metadata/data_tables?collection=ihgis&version=2&pageSize=10" \
-H "Authorization: $MY_KEY" | jq
# Results
{
"data": [
{
"name": "AE2005pop.AAA",
"datasetName": "AE2005pop",
"label": "Population by Nationality and Sex [1975]",
"universe": "Total population",
"tableNum": "1",
"sequence": 1,
"tabulationGeographies": [
"AE2005pop.g0",
"AE2005pop.g1"
],
"footnotes": [
"Source: 1975 Census (Ministry of Economy)"
]
},
{
"name": "AL2001pop.AAA",
"datasetName": "AL2001pop",
"label": "Resident Population and Households",
"universe": "Varies",
"tableNum": "1.1",
"sequence": 1,
"tabulationGeographies": [
"AL2001pop.g0"
],
"footnotes": [
"IPUMS: Old age index = (P 65+ / P 0-15 x 100), Dependence index = ((P>15 + P+ 64) / P 15-65 x 100), Substitution index = (P 60-64 / P 15-19 x 100)"
]
},
[SNIP]
{
"name": "AR1991tab.AAA",
"datasetName": "AR1991tab",
"label": "Total Population",
"universe": "Total population",
"tableNum": "T01",
"sequence": 1,
"tabulationGeographies": [
"AR1991tab.g0",
"AR1991tab.g1",
"AR1991tab.g2"
],
"footnotes": []
},
{
"name": "AR2001tab.AAA",
"datasetName": "AR2001tab",
"label": "Total Population",
"universe": "Total population",
"tableNum": "T01",
"sequence": 1,
"tabulationGeographies": [
"AR2001tab.g0",
"AR2001tab.g1",
"AR2001tab.g2"
],
"footnotes": []
}
],
"pageNumber": 1,
"pageSize": 10,
"totalCount": 15713,
"links": {
"previousPage": null,
"nextPage": "https://api.ipums.org/metadata/data_tables?collection=ihgis&pageNumber=2&pageSize=10&version=2"
}
}Note that this is a paginated endpoint. The default page size is 500 items, but here we have used the pageSize parameter to set 10 items per page. The links->nextPage field contains the URL to retrieve the next page of results.
Get Detailed Metadata for a Single Data Table
This API call will return the details of a single data table, AE2005pop.AAA in this example. The details include the tabulation geographies for which the table is available, a listing of the variables (columns) in the table, and any footnotes present for the table.
curl -X GET \
"https://api.ipums.org/metadata/datasets/AE2005pop/data_tables/AE2005pop.AAA?collection=ihgis&version=2" \
-H "Authorization: $MY_KEY" | jq
# Results
{
"name": "AE2005pop.AAA",
"datasetName": "AE2005pop",
"label": "Population by Nationality and Sex [1975]",
"universe": "Total population",
"tableNum": "1",
"sequence": 1,
"tabulationGeographies": [
"AE2005pop.g0",
"AE2005pop.g1"
],
"footnotes": [
"Source: 1975 Census (Ministry of Economy)"
],
"variables": [
{
"name": "AE2005pop.AAA.001",
"label": "UAE Citizen : Male",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 1
},
{
"name": "AE2005pop.AAA.002",
"label": "UAE Citizen : Female",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 2
},
{
"name": "AE2005pop.AAA.003",
"label": "UAE Citizen",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 3
},
{
"name": "AE2005pop.AAA.004",
"label": "Non-national : Male",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 4
},
{
"name": "AE2005pop.AAA.005",
"label": "Non-national : Female",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 5
},
{
"name": "AE2005pop.AAA.006",
"label": "Non-national",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 6
},
{
"name": "AE2005pop.AAA.007",
"label": "Male",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 7
},
{
"name": "AE2005pop.AAA.008",
"label": "Female",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 8
},
{
"name": "AE2005pop.AAA.009",
"label": "Total",
"dataYear": "1975",
"universe": "Total population",
"aggMethod": "Count",
"aggDetail": "",
"sequence": 9
}
]
}Data Table Attributes
name: The unique identifier of the data table.datasetName: The unique identifier of the dataset the table belongs to.label: The title of the table.universe: The statistical population (set of entities) measured by this data table, including any restrictions on who or what was included (e.g., population age 15 and over, resident households, agricultural holdings, etc.). If different variables in the table cover different universes, the table-level universe will be “varies.”tableNum: The number designating the table in the source publication.sequence: The order in which this data table will appear in the metadata API and extract metadata.tabulationGeographies: A listing of the tabulation geographies for which this table is available.footnotes: A listing of any explanatory footnotes associated with the table.variables: A listing of the variables (columns) within the tablename: The unique identifier of the variable.label: A description of the variable.dataYear: The year represented by the data in the variable. In most cases, this is the year of the census. But it may be a prior year for historical data or a future year for projections.universe: The set of entities measured for this variable.aggMethod: The method by which information from individual enumeration forms was aggregated to create this variable (e.g., count, percent, median).aggDetail: Any additional details describing how the data were aggregated.sequence: The order in which the variable appears within the table.
Tabulation Geographies
IHGIS tabulation geographies are sets of units over which information from individual enumeration forms is summarized. Most tabulation geographies reflect an exhaustive and exclusive division of the country and are organized into hierarchies of child units nested within parent units (e.g., states, provinces, districts). Some tabulation geographies (e.g., major cities) may not cover the entire country. Shapefiles delineating the boundaries of most tabulation geographies are available for download from the IHGIS Geography & GIS website.
Get All Tabulation Geographies
This API call will return a list of all available tabulation geographies. The unique identifier for each tabulation geography is in the name field.
curl -X GET \
"https://api.ipums.org/metadata/tabulation_geographies?collection=ihgis&version=2&pageSize=10" \
-H "Authorization: $MY_KEY" | jq
# Results
{
"data": [
{
"name": "AE2005pop.g0",
"label": "Nation",
"hierarchicalLevel": "g0",
"meanPopulation": 4106427,
"meanArea": 70748.5,
"sequence": 1,
"unitCount": 1
},
{
"name": "AE2005pop.g1",
"label": "Emirates",
"hierarchicalLevel": "g1",
"meanPopulation": 586632,
"meanArea": 10106.9,
"sequence": 2,
"unitCount": 7
},
[SNIP]
{
"name": "AM2001tab.ga",
"label": "Provinces",
"hierarchicalLevel": "ga",
"meanPopulation": 296873,
"meanArea": 2593.6,
"sequence": 3,
"unitCount": 11
},
{
"name": "AM2011tab.g0",
"label": "Nation",
"hierarchicalLevel": "g0",
"meanPopulation": 3018310,
"meanArea": 28529.1,
"sequence": 1,
"unitCount": 1
}
],
"pageNumber": 1,
"pageSize": 10,
"totalCount": 1484,
"links": {
"previousPage": null,
"nextPage": "https://api.ipums.org/metadata/tabulation_geographies?collection=ihgis&pageNumber=2&pageSize=10&version=2"
}
}Note that this is a paginated endpoint. The default page size is 500 items, but here we have used the pageSize parameter to set 10 items per page. The links->nextPage field contains the URL to retrieve the next page of results.
Tabulation Geography Attributes
name: The unique identifier of the tabulation geography.label: The name of the type of units in the tabulation geography (e.g., states, provinces, districts).hierarchicalLevel: The level of the nesting structure at which the tabulation geography sits. Hierarchical levels in the primary nesting structure for the country are designated with ‘g’ and a number, where lower numbers indicate larger units and higher numbers indicate smaller nested units (e.g., g2 units nest within g1 units). Hierarchical levels designated with ‘g’ and a letter (e.g., ga) are outside the primary nesting structure and may cross the boundaries of units in the primary hierarchy and/or may not cover the entire country.meanPopulation: The mean population of the units in the tabulation geography.meanArea: The mean area of the units in the tabulation geography, in square kilometers.sequence: The order in which the tabulation geography will appear in the metadata API and extract metadata.unitCount: The number of units in the tabulation geography.