Documentation
> Workflows & Code
> Explore Metadata
> IPUMS NHGIS Metadata
> Time Series Metadata
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, zctacurl -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 25curl -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.