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=beta"
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']},
 {'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']},
 {'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']},
 {'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']},
 {'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',
  'sequence': 10.01,
...
url <- "https://api.ipums.org/metadata/nhgis/time_series_tables?version=beta"
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  B57                Persons by Age [18]                Nominal    20.01
12  AX8                Persons by Age [22]                Nominal    20.02
13  CW3                Persons by Age [22]   Standardized to 2010    20.03
14  CN5                Persons by Age [23]   Standardized to 2010    20.04
15  A38      Persons by Detailed Age [101]                Nominal    20.05
16  AT3      Persons by Detailed Age [103]                Nominal    20.06
17  CW4 Persons Under 20 Years by Age [14]   Standardized to 2010    20.07
18  CN6 Persons Under 20 Years by Age [20]   Standardized to 2010    20.08
19  AR9              Median Age of Persons                Nominal    25.01
20  B58     Persons by Sex [2] by Age [18]                Nominal    30.01
                                                                                                                                      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
2                                                                                                         1970, 1980, 1990, 2000, 2010, 125
3                                                                                                               1980, 1990, 2000, 2010, 125
4                                                                                                                          2000, 2010, 1990
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
10                                                                                                                         2000, 2010, 1990
11                                                                                                             1970, 1980, 1990, 2000, 2010
12                                                                                                                   1970, 1990, 2000, 2010
13                                                                                                                         1990, 2000, 2010
14                                                                                                                               2000, 2010
15                                                                                                             1970, 1980, 1990, 2000, 2010
16                                                                                                                   1980, 1990, 2000, 2010
17                                                                                                                         1990, 2000, 2010
18                                                                                                                               2000, 2010
19                                                                                                                   1980, 1990, 2000, 2010
20                                                                                                             1970, 1980, 1990, 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, cty_sub, place
13 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
14 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
15                                                        state, county, cty_sub
16                              nation, region, division, state, county, cty_sub
17 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
18 state, county, tract, blck_grp, cty_sub, place, cd111th, cbsa, urb_area, zcta
19                                       nation, region, division, state, county
20                                          state, county, tract, cty_sub, place
curl -X GET \
  https://api.ipums.org/metadata/nhgis/time_series_tables?version=beta \
  -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"
    ],
    "geog_levels": [
      "state",
      "county"
    ]
  },
  {
    "name": "AV0",
    "description": "Total Population",
    "geographic_integration": "Nominal",
    "sequence": 0.02,
    "years": [
      "1970",
      "1980",
      "1990",
      "2000",
      "2010",
      "125"
    ],
    "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"
    ],
    "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"
    ],
    "geog_levels": [
      "state",
      "county",
      "tract",
      "blck_grp",
      "cty_sub",
      "place",
      "cd111th",
      "cbsa",
      "urb_area",
      "zcta"
...

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=beta"
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}]}
...
url <- "https://api.ipums.org/metadata/nhgis/time_series_tables/A00?version=beta"
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

$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=beta \
  -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.