Documentation > Workflows & Code > Explore Metadata > NHGIS > Dataset Metadata

IPUMS NHGIS Dataset Metadata

NHGIS summary tables are organized into datasets distinguished by the years, geographic levels and topics they cover; by the data source and survey coverage (e.g., sample-based vs. 100% count); and by the breakdown variables available. An overview of datasets and a catalog of source documentation are available on the NHGIS website.

Below we provide examples in curl showing how to work with our API to access metadata about NHGIS datasets.

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 High-Level Metadata for All Datasets

Get All Datasets

This API call will return a list of all available datasets. The entry for each dataset includes metadata for the dataset’s name and description. 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=nhgis&version=2" \
  -H "Authorization: $MY_KEY" | jq

# Results 

{
  "data": [
    {
      "name": "1790_cPop",
      "group": "1790 Census",
      "description": "Population Data [US, States & Counties]",
      "sequence": 101
    },
    {
      "name": "1800_cPop",
      "group": "1800 Census",
      "description": "Population Data [US, States & Counties]",
      "sequence": 201
    },

[SNIP]

    {
      "name": "2017_2021_ACS5c",
      "group": "2021 American Community Survey",
      "description": "5-Year Data [2017-2021, Summary by Residence 1 Year Ago]",
      "sequence": 6004
    },
    {
      "name": "2017_2021_ACS5d",
      "group": "2021 American Community Survey",
      "description": "5-Year Data [2017-2021, Summary by Place of Work]",
      "sequence": 6005
    }
  ],
  "pageNumber": 1,
  "pageSize": 500,
  "totalCount": 253,
  "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 253 in this example, the links->nextPage field would have a URL to retrieve the next page of results.

Get All Data Tables

This API call will return a list of all available data tables across all datasets. Since IPUMS NHGIS contains collections of related datasets (e.g. the 2021 5-year ACS summary files are split across four datasets), this endpoint can be useful for retrieving lists of data tables across related datasets. It can also be used for finding all data tables with a specific keyword in their description or universe.

curl -X GET \
  "https://api.ipums.org/metadata/data_tables?collection=nhgis&version=2" \
  -H "Authorization: $MY_KEY" | jq

# Results 

{
  "data": [
    {
      "name": "NT1",
      "description": "Total Population",
      "universe": "Persons",
      "nhgisCode": "AAA",
      "sequence": 1,
      "datasetName": "1790_cPop",
      "nVariables": 1
    },
    {
      "name": "NT2",
      "description": "Urban Population (Incorporated Places 2,500 and Over)",
      "universe": "Urban Persons (Incorporated Places 2,500 and Over)",
      "nhgisCode": "AAK",
      "sequence": 2,
      "datasetName": "1790_cPop",
      "nVariables": 1
    },
    {
      "name": "NT3",
      "description": "Urban Population in Cities of 25,000 and Over",
      "universe": "Urban Persons in Cities of 25,000 and Over",
      "nhgisCode": "AAN",
      "sequence": 3,
      "datasetName": "1790_cPop",
      "nVariables": 1
    },

[SNIP]

    {
      "name": "NT9",
      "description": "Total Number of People Employed in All Classes of Occupations",
      "universe": "Employed Persons",
      "nhgisCode": "ALY",
      "sequence": 9,
      "datasetName": "1870_sROG",
      "nVariables": 1
    },
    {
      "name": "NT10",
      "description": "People Employed in All Classes of Occupations by Age by Sex",
      "universe": "Employed Persons",
      "nhgisCode": "ALI",
      "sequence": 10,
      "datasetName": "1870_sROG",
      "nVariables": 6
    },
    {
      "name": "NT11",
      "description": "People Employed in All Classes of Occupations by Place of Birth",
      "universe": "Employed Persons",
      "nhgisCode": "ALJ",
      "sequence": 11,
      "datasetName": "1870_sROG",
      "nVariables": 13
    }
  ],
  "pageNumber": 1,
  "pageSize": 500,
  "totalCount": 46031,
  "links": {
    "previousPage": null,
    "nextPage": "https://api.ipums.org/metadata/data_tables?collection=nhgis&pageNumber=2&pageSize=500&version=2"
  }
}

Note that this is a paginated endpoint. The default page size is 500 items. As there are more than 500 items in this example, the links->nextPage field contains the 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, 1790_cPop in this example. The details include the name and description of each each table within the dataset, as well as the geographic levels for which this dataset is available.

curl -X GET \
  "https://api.ipums.org/metadata/datasets/1790_cPop?collection=nhgis&version=2" \
  -H "Authorization: $MY_KEY" | jq

# Results 

{
  "name": "1790_cPop",
  "nhgisId": "ds1",
  "group": "1790 Census",
  "description": "Population Data [US, States & Counties]",
  "sequence": 101,
  "hasMultipleDataTypes": false,
  "dataTables": [
    {
      "name": "NT1",
      "nhgisCode": "AAA",
      "description": "Total Population",
      "sequence": 1
    },
    {
      "name": "NT2",
      "nhgisCode": "AAK",
      "description": "Urban Population (Incorporated Places 2,500 and Over)",
      "sequence": 2
    },
    {
      "name": "NT3",
      "nhgisCode": "AAN",
      "description": "Urban Population in Cities of 25,000 and Over",
      "sequence": 3
    },
    {
      "name": "NT4",
      "nhgisCode": "AAO",
      "description": "White Males and Estimated White Females by Sex by Age",
      "sequence": 4
    },
    {
      "name": "NT5",
      "nhgisCode": "AAP",
      "description": "White Population by Sex",
      "sequence": 5
    },
    {
      "name": "NT6",
      "nhgisCode": "AAQ",
      "description": "Race/Slave Status",
      "sequence": 6
    },
    {
      "name": "NT9",
      "nhgisCode": "AAR",
      "description": "Total Number of Families",
      "sequence": 7
    },
    {
      "name": "NT10",
      "nhgisCode": "AAB",
      "description": "Number of Family Members",
      "sequence": 8
    },
    {
      "name": "NT12",
      "nhgisCode": "AAC",
      "description": "White Population by Nationality",
      "sequence": 9
    },
    {
      "name": "NT13",
      "nhgisCode": "AAD",
      "description": "Families by Slaveholding Status",
      "sequence": 10
    },
    {
      "name": "NT14",
      "nhgisCode": "AAE",
      "description": "Families by Slaveholding Status by Race",
      "sequence": 11
    },
    {
      "name": "NT15",
      "nhgisCode": "AAF",
      "description": "White Family Members by Slaveholding Status",
      "sequence": 12
    },
    {
      "name": "NT16",
      "nhgisCode": "AAG",
      "description": "Average Number of Members in White Families by Slaveholding Status",
      "sequence": 13
    },
    {
      "name": "NT17",
      "nhgisCode": "AAH",
      "description": "Percent of Families by Slaveholding Status by Race",
      "sequence": 14
    },
    {
      "name": "NT18",
      "nhgisCode": "AAI",
      "description": "Total Number of Slaves",
      "sequence": 15
    },
    {
      "name": "NT19",
      "nhgisCode": "AAJ",
      "description": "Average Number of Slaves per Slaveholding Family",
      "sequence": 16
    },
    {
      "name": "NT20",
      "nhgisCode": "AAL",
      "description": "Slaveholding Families by Number of Slaves",
      "sequence": 17
    },
    {
      "name": "NT21",
      "nhgisCode": "AAM",
      "description": "Race",
      "sequence": 18
    }
  ],
  "geogLevels": [
    {
      "name": "nation",
      "description": "Nation",
      "hasGeogExtentSelection": false,
      "sequence": 1
    },
    {
      "name": "state",
      "description": "State",
      "hasGeogExtentSelection": false,
      "sequence": 4
    },
    {
      "name": "county",
      "description": "State--County",
      "hasGeogExtentSelection": false,
      "sequence": 25
    }
  ],
  "geographicInstances": [
    {
    "name": "090",
    "description": "Connecticut"
    },
    {
    "name": "100",
    "description": "Delaware"
    },
    {
    "name": "130",
    "description": "Georgia"
    },
    {
    "name": "240",
    "description": "Maryland"
    },
    {
    "name": "250",
    "description": "Massachusetts"
    },
    {
    "name": "330",
    "description": "New Hampshire"
    },
    {
    "name": "340",
    "description": "New Jersey"
    },
    {
    "name": "360",
    "description": "New York"
    },
    {
    "name": "370",
    "description": "North Carolina"
    },
    {
    "name": "420",
    "description": "Pennsylvania"
    },
    {
    "name": "440",
    "description": "Rhode Island"
    },
    {
    "name": "450",
    "description": "South Carolina"
    },
    {
    "name": "500",
    "description": "Vermont"
    },
    {
    "name": "510",
    "description": "Virginia"
    }
  ]
}

Dataset Attributes

name: The unique identifier of the dataset.
group: The group of datasets to which this dataset belongs.
description: A short description of the dataset.
sequence: The order in which the dataset will appear in the metadata API and extracts.
hasMultipleDataTypes: A boolean indicating if multiple data types exist for this dataset. For example, the American Community Survey datasets have margins of error as well as estimate data types. Use the breakdownAndDataTypeLayout parameter on your extract to specify how these data types are structured in your extract.
dataTables: A list of data tables available for this dataset.
geogLevels: A list of geographic levels available for this dataset.
- name: The unique identifier of the geographic level.
- description: A short description of the geographic level.
- hasGeogExtentSelection: Whether or not extent selection is applied for this geography level. See geographicInstances for a list of valid extents.
breakdowns: A list of breakdowns available for this dataset.
years: (Optional) If a dataset includes data from multiple years, then this is a list of its years.
geographicInstances: (Optional) If a dataset has any geographic levels that have extent selection, then this a list of the valid extents for this dataset.

Get Metadata for a Table

This API call will return the metadata details for a specific table, NP19 from 1990_STF1 in this example. This includes the NHGIS code, which appears in the codebook and is prepended to the variable names in the extract. The universe information is also returned, along with codes and descriptions for each variable.

curl -X GET \
  "https://api.ipums.org/metadata/datasets/1990_STF1/data_tables/NP19?collection=nhgis&version=2" \
  -H "Authorization: $MY_KEY"

# Results 

{
  "name": "NP19",
  "description": "Race of Householder by Household Type",
  "universe": "Households",
  "nhgisCode": "EUC",
  "sequence": 20,
  "datasetName": "1990_STF1",
  "variables": [
    {
      "description": "White >> Family households: Married-couple family: With related children",
      "nhgisCode": "EUC001"
    },
    {
      "description": "White >> Family households: Married-couple family: No related children",
      "nhgisCode": "EUC002"
    },
    {
      "description": "White >> Family households: Other family: Male householder, no wife present: With related children",
      "nhgisCode": "EUC003"
    },
    {
      "description": "White >> Family households: Other family: Male householder, no wife present: No related children",
      "nhgisCode": "EUC004"
    },
    {
      "description": "White >> Family households: Other family: Female householder, no husband present: With related children",
      "nhgisCode": "EUC005"
    },
    {
      "description": "White >> Family households: Other family: Female householder, no husband present: No related children",
      "nhgisCode": "EUC006"
    },
    {
      "description": "White >> Nonfamily households: Householder living alone",
      "nhgisCode": "EUC007"
    },
    {
      "description": "White >> Nonfamily households: Householder not living alone",
      "nhgisCode": "EUC008"
    },
    {
      "description": "Black >> Family households: Married-couple family: With related children",
      "nhgisCode": "EUC009"
    },
    {
      "description": "Black >> Family households: Married-couple family: No related children",
      "nhgisCode": "EUC010"
    },
    {
      "description": "Black >> Family households: Other family: Male householder, no wife present: With related children",
      "nhgisCode": "EUC011"
    },
    {
      "description": "Black >> Family households: Other family: Male householder, no wife present: No related children",
      "nhgisCode": "EUC012"
    },
    {
      "description": "Black >> Family households: Other family: Female householder, no husband present: With related children",
      "nhgisCode": "EUC013"
    },
    {
      "description": "Black >> Family households: Other family: Female householder, no husband present: No related children",
      "nhgisCode": "EUC014"
    },
    {
      "description": "Black >> Nonfamily households: Householder living alone",
      "nhgisCode": "EUC015"
    },
    {
      "description": "Black >> Nonfamily households: Householder not living alone",
      "nhgisCode": "EUC016"
    },
    {
      "description": "American Indian, Eskimo, or Aleut >> Family households: Married-couple family: With related children",
      "nhgisCode": "EUC017"
    },
    {
      "description": "American Indian, Eskimo, or Aleut >> Family households: Married-couple family: No related children",
      "nhgisCode": "EUC018"
    },
    {
      "description": "American Indian, Eskimo, or Aleut >> Family households: Other family: Male householder, no wife present: With related children",
      "nhgisCode": "EUC019"
    },
    {
      "description": "American Indian, Eskimo, or Aleut >> Family households: Other family: Male householder, no wife present: No related children",
      "nhgisCode": "EUC020"
    },
    {
      "description": "American Indian, Eskimo, or Aleut >> Family households: Other family: Female householder, no husband present: With related children",
      "nhgisCode": "EUC021"
    },
    {
      "description": "American Indian, Eskimo, or Aleut >> Family households: Other family: Female householder, no husband present: No related children",
      "nhgisCode": "EUC022"
    },
    {
      "description": "American Indian, Eskimo, or Aleut >> Nonfamily households: Householder living alone",
      "nhgisCode": "EUC023"
    },
    {
      "description": "American Indian, Eskimo, or Aleut >> Nonfamily households: Householder not living alone",
      "nhgisCode": "EUC024"
    },
    {
      "description": "Asian or Pacific Islander >> Family households: Married-couple family: With related children",
      "nhgisCode": "EUC025"
    },
    {
      "description": "Asian or Pacific Islander >> Family households: Married-couple family: No related children",
      "nhgisCode": "EUC026"
    },
    {
      "description": "Asian or Pacific Islander >> Family households: Other family: Male householder, no wife present: With related children",
      "nhgisCode": "EUC027"
    },
    {
      "description": "Asian or Pacific Islander >> Family households: Other family: Male householder, no wife present: No related children",
      "nhgisCode": "EUC028"
    },
    {
      "description": "Asian or Pacific Islander >> Family households: Other family: Female householder, no husband present: With related children",
      "nhgisCode": "EUC029"
    },
    {
      "description": "Asian or Pacific Islander >> Family households: Other family: Female householder, no husband present: No related children",
      "nhgisCode": "EUC030"
    },
    {
      "description": "Asian or Pacific Islander >> Nonfamily households: Householder living alone",
      "nhgisCode": "EUC031"
    },
    {
      "description": "Asian or Pacific Islander >> Nonfamily households: Householder not living alone",
      "nhgisCode": "EUC032"
    },
    {
      "description": "Other race >> Family households: Married-couple family: With related children",
      "nhgisCode": "EUC033"
    },
    {
      "description": "Other race >> Family households: Married-couple family: No related children",
      "nhgisCode": "EUC034"
    },
    {
      "description": "Other race >> Family households: Other family: Male householder, no wife present: With related children",
      "nhgisCode": "EUC035"
    },
    {
      "description": "Other race >> Family households: Other family: Male householder, no wife present: No related children",
      "nhgisCode": "EUC036"
    },
    {
      "description": "Other race >> Family households: Other family: Female householder, no husband present: With related children",
      "nhgisCode": "EUC037"
    },
    {
      "description": "Other race >> Family households: Other family: Female householder, no husband present: No related children",
      "nhgisCode": "EUC038"
    },
    {
      "description": "Other race >> Nonfamily households: Householder living alone",
      "nhgisCode": "EUC039"
    },
    {
      "description": "Other race >> Nonfamily households: Householder not living alone",
      "nhgisCode": "EUC040"
    }
  ]
}

Data Table Attributes

name: The unique identifier for the data table within its dataset.
description: A short description of the data table.
universe: The statistical population (set of entities) measured by this data table (e.g., persons, families, occupied housing units, etc.).
nhgisCode: The code for this data table that will appear in extract.
sequence: The order for which this data table will appear in the metadata API and extracts.
variables: A list of variables within the table.