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).

import requests
import json
from pprint import pprint

my_headers = {"Authorization": my_key}

nhgis_metadata = requests.get("https://api.ipums.org/des/metadata/agg/nhgis/vbeta/time_series_tables", headers=my_headers)

pprint(nhgis_metadata.json())

# output sample: 

[{'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']},
  ...
]
result <- GET("https://api.ipums.org/des/metadata/agg/nhgis/vbeta/time_series_tables", add_headers(Authorization = my_key))
res_df <- content(result, "parsed", simplifyDataFrame = TRUE)
res_df # Contains metadata

# res_df will contain a response like:

    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
[SNIP]
166  AA3                                                             Persons in Group Quarters by Detailed Group Quarters Type [6]                Nominal   500.07
                                                                                                                                       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
[SNIP]
166                                                                                                             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
[SNIP]
166                                                        state, county, cty_sub
curl -X GET   https://demo.api.ipums.org/demo-des/metadata/agg/nhgis/vbeta/time_series_tables -H 'Content-Type: application/json' -H 'Authorization: ' + my_key

# will generate a JSON response like:

[
    {
        "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"
        ]
    },
   ...

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.

nhgis_A00 = requests.get("https://api.ipums.org/des/metadata/agg/nhgis/vbeta/time_series_tables/A00", headers=my_headers)
pprint(nhgis_A00.json())

# This outputs:

{'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}]}
result <- GET("https://api.ipums.org/des/metadata/agg/nhgis/vbeta/time_series_tables/A00", add_headers(Authorization = my_key))
results <- content(result, "parsed", simplifyDataFrame = TRUE)
results # Contains metadata

# Results contains:

$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

$geog_levels
    name   description sequence
1  state         State        4
2 county State--County       25

$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
curl -X GET \
  https://api.ipums.org/des/metadata/agg/nhgis/vbeta/time_series_tables/A00 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ' + my_key

# This returns:

{
    "name": "A00",
    "description": "Total Population",
    "geographic_integration": "Nominal",
    "sequence": 0.01,
    "time_series": [
        {
            "name": "AA",
            "description": "Persons: Total",
            "sequence": 1
        }
    ],
    "geog_levels": [
        {
            "name": "state",
            "description": "State",
            "sequence": 4
        },
        {
            "name": "county",
            "description": "State--County",
            "sequence": 25
        }
    ],
    "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",
            "sequence": 78
        },
        {
            "name": "1970",
            "description": "1970",
            "sequence": 88
        },
        {
            "name": "1980",
            "description": "1980",
            "sequence": 98
        },
        {
            "name": "1990",
            "description": "1990",
            "sequence": 108
        },
        {
            "name": "2000",
            "description": "2000",
            "sequence": 118
        },
        {
            "name": "2010",
            "description": "2010",
            "sequence": 131
        }
    ]
}