IPUMS NHGIS Time Series Metadata

An NHGIS time series table links together comparable statistics from multiple datasets into one table. An in-depth introduction and a full catalog of NHGIS time series tables are availble on the NHGIS website.

Get High-Level Metadata for Time Series Tables

This API call will return a list of all available time series tables. The entry for each time series table includes metadata for the table’s description, geographic levels, year availability, and geographic integration. The unique identifier for each time series table is in the name field. This is needed for retrieving details about a single time series table (see next section).

my_headers = {"Authorization": my_key}
url = "https://api.ipums.org/metadata/nhgis/time_series_tables?version=v1"
nhgis_metadata = requests.get(url, headers=my_headers)
pprint(nhgis_metadata.json())
      
# Results
[{'description': 'Total Population',
  'geog_levels': ['state', 'county'],
  'geographic_integration': 'Nominal',
  'name': 'A00',
  'sequence': 0.01,
  'years': ['1790',
            '1800',
            '1810',
            '1820',
            '1830',
            '1840',
            '1850',
            '1860',
            '1870',
            '1880',
            '1890',
            '1900',
            '1910',
            '1920',
            '1930',
            '1940',
            '1950',
            '1960',
            '1970',
            '1980',
            '1990',
            '2000',
            '2010',
            '2020']},
 {'description': 'Total Population',
  'geog_levels': ['state', 'county', 'tract', 'cty_sub', 'place'],
  'geographic_integration': 'Nominal',
  'name': 'AV0',
  'sequence': 0.02,
  'years': ['1970', '1980', '1990', '2000', '2010', '125', '2020', '195']},
 {'description': 'Total Population',
  'geog_levels': ['nation',
                  'region',
                  'division',
                  'state',
                  'county',
                  'tract',
                  'cty_sub',
                  'place'],
  'geographic_integration': 'Nominal',
  'name': 'B78',
  'sequence': 0.03,
  'years': ['1980', '1990', '2000', '2010', '125', '2020', '195']},
 {'description': 'Total Population',
  'geog_levels': ['state',
                  'county',
                  'tract',
                  'blck_grp',
                  'cty_sub',
                  'place',
                  'cd111th',
                  'cbsa',
                  'urb_area',
                  'zcta'],
  'geographic_integration': 'Standardized to 2010',
  'name': 'CL8',
  'sequence': 0.04,
  'years': ['2000', '2010', '1990', '2020']},
 {'description': 'Persons by Urban/Rural Status [4]',
  'geog_levels': ['state', 'county', 'cty_sub', 'place'],
  'geographic_integration': 'Nominal',
  'name': 'A57',
  'sequence': 5.01,
  'years': ['1970', '1980', '1990', '2000', '2010']},
 {'description': 'Persons by Urban/Rural Status [4]',
  'geog_levels': ['nation',
                  'region',
                  'division',
                  'state',
                  'county',
                  'tract',
                  'cty_sub',
                  'place'],
  'geographic_integration': 'Nominal',
  'name': 'A59',
  'sequence': 5.02,
  'years': ['1980', '1990', '2000', '2010']},
 {'description': 'Persons by Urban/Rural Status [4]',
  'geog_levels': ['state',
                  'county',
                  'tract',
                  'blck_grp',
                  'cty_sub',
                  'place',
                  'cd111th',
                  'cbsa',
                  'urb_area',
                  'zcta'],
  'geographic_integration': 'Standardized to 2010',
  'name': 'CL9',
  'sequence': 5.03,
  'years': ['2010', '1990', '2000']},
 {'description': 'Persons by Sex [2]',
  'geog_levels': ['state', 'county'],
  'geographic_integration': 'Nominal',
  'name': 'A08',
...
url <- "https://api.ipums.org/metadata/nhgis/time_series_tables?version=v1"
result <- GET(url, add_headers(Authorization = my_key))
res_df <- content(result, "parsed", simplifyDataFrame = TRUE)
head(res_df, n = 20L) # Contains metadata
      
# Results
   name                             description geographic_integration sequence
1   A00                        Total Population                Nominal     0.01
2   AV0                        Total Population                Nominal     0.02
3   B78                        Total Population                Nominal     0.03
4   CL8                        Total Population   Standardized to 2010     0.04
5   A57       Persons by Urban/Rural Status [4]                Nominal     5.01
6   A59       Persons by Urban/Rural Status [4]                Nominal     5.02
7   CL9       Persons by Urban/Rural Status [4]   Standardized to 2010     5.03
8   A08                      Persons by Sex [2]                Nominal    10.01
9   AV1                      Persons by Sex [2]                Nominal    10.02
10  CM0                      Persons by Sex [2]   Standardized to 2010    10.03
11  D08 Persons by Age [2]: Children and Adults                Nominal    20.01
12  D06 Persons by Age [2]: Children and Adults   Standardized to 2010    20.02
13  B57                     Persons by Age [18]                Nominal    20.03
14  AX8                     Persons by Age [22]                Nominal    20.04
15  CW3                     Persons by Age [22]   Standardized to 2010    20.05
16  CN5                     Persons by Age [23]   Standardized to 2010    20.06
17  A38           Persons by Detailed Age [101]                Nominal    20.07
18  AT3           Persons by Detailed Age [103]                Nominal    20.08
19  CW4      Persons Under 20 Years by Age [14]   Standardized to 2010    20.09
20  CN6      Persons Under 20 Years by Age [20]   Standardized to 2010    20.10
                                                                                                                                            years
1  1790, 1800, 1810, 1820, 1830, 1840, 1850, 1860, 1870, 1880, 1890, 1900, 1910, 1920, 1930, 1940, 1950, 1960, 1970, 1980, 1990, 2000, 2010, 2020
2                                                                                                    1970, 1980, 1990, 2000, 2010, 125, 2020, 195
3                                                                                                          1980, 1990, 2000, 2010, 125, 2020, 195
4                                                                                                                          2000, 2010, 1990, 2020
5                                                                                                                    1970, 1980, 1990, 2000, 2010
6                                                                                                                          1980, 1990, 2000, 2010
7                                                                                                                                2010, 1990, 2000
8                          2010, 1860, 1870, 1880, 1890, 1900, 1910, 1920, 1930, 1940, 1950, 1960, 1970, 1980, 1990, 2000, 1820, 1830, 1840, 1850
9                                                                                                          1970, 1980, 1990, 2000, 2010, 125, 195
10                                                                                                                               2000, 2010, 1990
11                                                                                                             1990, 2000, 2010, 2020, 1970, 1980
12                                                                                                                         2000, 2010, 2020, 1990
13                                                                                                                   1970, 1980, 1990, 2000, 2010
14                                                                                                                         1970, 1990, 2000, 2010
15                                                                                                                               1990, 2000, 2010
16                                                                                                                                     2000, 2010
17                                                                                                                   1970, 1980, 1990, 2000, 2010
18                                                                                                                         1980, 1990, 2000, 2010
19                                                                                                                               1990, 2000, 2010
20                                                                                                                                     2000, 2010
                                                                     geog_levels
1                                                                  state, county
2                                           state, county, tract, cty_sub, place
3                 nation, region, division, state, county, tract, cty_sub, place
4  state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
5                                                  state, county, cty_sub, place
6                 nation, region, division, state, county, tract, cty_sub, place
7  state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
8                                                                  state, county
9                                           state, county, tract, cty_sub, place
10 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
11                                          state, county, tract, cty_sub, place
12 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
13                                          state, county, tract, cty_sub, place
14                                          state, county, tract, cty_sub, place
15 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
16 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
17                                                        state, county, cty_sub
18                              nation, region, division, state, county, cty_sub
19 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
20 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
curl -X GET \
  https://api.ipums.org/metadata/nhgis/time_series_tables?version=v1 \
  -H 'Content-Type: application/json' \
  -H "Authorization: $MY_KEY"
      
# Results
[
  {
    "name": "A00",
    "description": "Total Population",
    "geographic_integration": "Nominal",
    "sequence": 0.01,
    "years": [
      "1790",
      "1800",
      "1810",
      "1820",
      "1830",
      "1840",
      "1850",
      "1860",
      "1870",
      "1880",
      "1890",
      "1900",
      "1910",
      "1920",
      "1930",
      "1940",
      "1950",
      "1960",
      "1970",
      "1980",
      "1990",
      "2000",
      "2010",
      "2020"
    ],
    "geog_levels": [
      "state",
      "county"
    ]
  },
  {
    "name": "AV0",
    "description": "Total Population",
    "geographic_integration": "Nominal",
    "sequence": 0.02,
    "years": [
      "1970",
      "1980",
      "1990",
      "2000",
      "2010",
      "125",
      "2020",
      "195"
    ],
    "geog_levels": [
      "state",
      "county",
      "tract",
      "cty_sub",
      "place"
    ]
  },
  {
    "name": "B78",
    "description": "Total Population",
    "geographic_integration": "Nominal",
    "sequence": 0.03,
    "years": [
      "1980",
      "1990",
      "2000",
      "2010",
      "125",
      "2020",
      "195"
    ],
    "geog_levels": [
      "nation",
      "region",
      "division",
      "state",
      "county",
      "tract",
      "cty_sub",
      "place"
    ]
  },
  {
    "name": "CL8",
    "description": "Total Population",
    "geographic_integration": "Standardized to 2010",
    "sequence": 0.04,
    "years": [
      "2000",
      "2010",
      "1990",
      "2020"
    ],
    "geog_levels": [
      "state",
      "county",
      "tract",
      "blck_grp",
...

Get Detailed Metadata for a Single Time Series Table

This API call will return the details of a single time series table, A00 in this example. The details repeat a lot of the information from the time series table call above, but also contain additional information on the individual time series contained within the table.

my_headers = {"Authorization": my_key}
url = "https://api.ipums.org/metadata/nhgis/time_series_tables/A00?version=v1"
nhgis_metadata = requests.get(url, headers=my_headers)
pprint(nhgis_metadata.json())
      
# Results
{'description': 'Total Population',
 'geog_levels': [{'description': 'State', 'name': 'state', 'sequence': 4},
                 {'description': 'State--County',
                  'name': 'county',
                  'sequence': 25}],
 'geographic_integration': 'Nominal',
 'name': 'A00',
 'sequence': 0.01,
 'time_series': [{'description': 'Persons: Total',
                  'name': 'AA',
                  'sequence': 1}],
 'years': [{'description': '1790', 'name': '1790', 'sequence': 1},
           {'description': '1800', 'name': '1800', 'sequence': 2},
           {'description': '1810', 'name': '1810', 'sequence': 3},
           {'description': '1820', 'name': '1820', 'sequence': 4},
           {'description': '1830', 'name': '1830', 'sequence': 5},
           {'description': '1840', 'name': '1840', 'sequence': 6},
           {'description': '1850', 'name': '1850', 'sequence': 7},
           {'description': '1860', 'name': '1860', 'sequence': 8},
           {'description': '1870', 'name': '1870', 'sequence': 12},
           {'description': '1880', 'name': '1880', 'sequence': 22},
           {'description': '1890', 'name': '1890', 'sequence': 29},
           {'description': '1900', 'name': '1900', 'sequence': 30},
           {'description': '1910', 'name': '1910', 'sequence': 32},
           {'description': '1920', 'name': '1920', 'sequence': 38},
           {'description': '1930', 'name': '1930', 'sequence': 48},
           {'description': '1940', 'name': '1940', 'sequence': 58},
           {'description': '1950', 'name': '1950', 'sequence': 68},
           {'description': '1960', 'name': '1960', 'sequence': 78},
           {'description': '1970', 'name': '1970', 'sequence': 88},
           {'description': '1980', 'name': '1980', 'sequence': 98},
           {'description': '1990', 'name': '1990', 'sequence': 108},
           {'description': '2000', 'name': '2000', 'sequence': 118},
           {'description': '2010', 'name': '2010', 'sequence': 131},
           {'description': '2020', 'name': '2020', 'sequence': 155}]}
...
url <- "https://api.ipums.org/metadata/nhgis/time_series_tables/A00?version=v1"
result <- GET(url, add_headers(Authorization = my_key))
res_df <- content(result, "parsed", simplifyDataFrame = TRUE)
head(res_df, n = 20L) # Contains metadata
      
# Results
$name
[1] "A00"

$description
[1] "Total Population"

$geographic_integration
[1] "Nominal"

$sequence
[1] 0.01

$time_series
  name    description sequence
1   AA Persons: Total        1

$years
   name description sequence
1  1790        1790        1
2  1800        1800        2
3  1810        1810        3
4  1820        1820        4
5  1830        1830        5
6  1840        1840        6
7  1850        1850        7
8  1860        1860        8
9  1870        1870       12
10 1880        1880       22
11 1890        1890       29
12 1900        1900       30
13 1910        1910       32
14 1920        1920       38
15 1930        1930       48
16 1940        1940       58
17 1950        1950       68
18 1960        1960       78
19 1970        1970       88
20 1980        1980       98
21 1990        1990      108
22 2000        2000      118
23 2010        2010      131
24 2020        2020      155

$geog_levels
    name   description sequence
1  state         State        4
2 county State--County       25
curl -X GET \
  https://api.ipums.org/metadata/nhgis/time_series_tables/A00?version=v1 \
  -H 'Content-Type: application/json' \
  -H "Authorization: $MY_KEY"
      
# Results
{
  "name": "A00",
  "description": "Total Population",
  "geographic_integration": "Nominal",
  "sequence": 0.01,
  "time_series": [
    {
      "name": "AA",
      "description": "Persons: Total",
      "sequence": 1
    }
  ],
  "years": [
    {
      "name": "1790",
      "description": "1790",
      "sequence": 1
    },
    {
      "name": "1800",
      "description": "1800",
      "sequence": 2
    },
    {
      "name": "1810",
      "description": "1810",
      "sequence": 3
    },
    {
      "name": "1820",
      "description": "1820",
      "sequence": 4
    },
    {
      "name": "1830",
      "description": "1830",
      "sequence": 5
    },
    {
      "name": "1840",
      "description": "1840",
      "sequence": 6
    },
    {
      "name": "1850",
      "description": "1850",
      "sequence": 7
    },
    {
      "name": "1860",
      "description": "1860",
      "sequence": 8
    },
    {
      "name": "1870",
      "description": "1870",
      "sequence": 12
    },
    {
      "name": "1880",
      "description": "1880",
      "sequence": 22
    },
    {
      "name": "1890",
      "description": "1890",
      "sequence": 29
    },
    {
      "name": "1900",
      "description": "1900",
      "sequence": 30
    },
    {
      "name": "1910",
      "description": "1910",
      "sequence": 32
    },
    {
      "name": "1920",
      "description": "1920",
      "sequence": 38
    },
    {
      "name": "1930",
      "description": "1930",
      "sequence": 48
    },
    {
      "name": "1940",
      "description": "1940",
      "sequence": 58
    },
    {
      "name": "1950",
      "description": "1950",
      "sequence": 68
    },
    {
      "name": "1960",
      "description": "1960",
...

Time Series Table Attributes

  • name: The unique identifier of the time series table.
  • description: A short description of the time series table.
  • geographic_integration: How the time series tables align geographic units across time. See our geographic integration method documentation.
  • sequence: The order in which the time series table will appear in the metadata API and extracts.
  • time_series: A list of time series for this time series table.
  • years: A list of years for this time series table.
  • geog_levels: A list of geographic levels available for this time series table.