Skip to contents

Get information about a specific API as a data frame

Usage

listCensusMetadata(
  name,
  vintage = NULL,
  type = "variables",
  group = NULL,
  variable_name = NULL,
  include_values = FALSE
)

Arguments

name

API programmatic name - e.g. acs/acs5. See list of names with listCensusApis().

vintage

Vintage (year) of dataset. Not required for timeseries APIs

type

Type of metadata to return. Options are: * `variables` (default) - list of variable names and descriptions for the dataset. * `geographies` - available geographies. * `groups` - available variable groups. Not used for all datasets. * `values` - encoded value labels for a given variable. Pair with `variable_name`. Not used for all datasets.

group

An optional variable group code, used to return metadata for a specific group of variables only. Variable groups are not used for all APIs.

variable_name

A name of a specific variable used to return value labels for that variable. Value labels are not published for all APIs.

include_values

Use with `type = "variables"`. Include value metadata for all variables in a dataset if value metadata exists. Default is "FALSE".

Examples

# \dontrun{

# List the variables available in the Small Area Health Insurance Estimates.
sahie_variables <- listCensusMetadata(
  name = "timeseries/healthins/sahie",
  type = "variables")
 head(sahie_variables)
#>        name
#> 1       for
#> 2        in
#> 3      time
#> 4 NIPR_LB90
#> 5   NIPR_PT
#> 6    AGECAT
#>                                                                                            label
#> 1                                                                   Census API FIPS 'for' clause
#> 2                                                                    Census API FIPS 'in' clause
#> 3                                                                       ISO-8601 Date/Time value
#> 4 Number in Demographic Group for Selected Income Range, Lower Bound for 90% Confidence Interval
#> 5                                Number in Demographic Group for Selected Income Range, Estimate
#> 6                                                                                   Age Category
#>                              concept predicateType group limit predicateOnly
#> 1 Census API Geography Specification      fips-for   N/A     0          TRUE
#> 2 Census API Geography Specification       fips-in   N/A     0          TRUE
#> 3 Census API Date/Time Specification      datetime   N/A     0          TRUE
#> 4                Uncertainty Measure           int   N/A     0          <NA>
#> 5                           Estimate           int   N/A     0          <NA>
#> 6                     Demographic ID           int   N/A     6          <NA>
#>            required
#> 1              <NA>
#> 2              <NA>
#> 3              true
#> 4              <NA>
#> 5              <NA>
#> 6 default displayed

# List the geographies available in the 5-year 2020 American Community Survey.
acs_geographies <- listCensusMetadata(
  name = "acs/acs5",
  vintage = 2020,
  type = "geographies")
 head(acs_geographies)
#>                 name geoLevelDisplay referenceDate      requires wildcard
#> 1                 us             010    2020-01-01          NULL     NULL
#> 2             region             020    2020-01-01          NULL     NULL
#> 3           division             030    2020-01-01          NULL     NULL
#> 4              state             040    2020-01-01          NULL     NULL
#> 5             county             050    2020-01-01         state    state
#> 6 county subdivision             060    2020-01-01 state, county   county
#>   optionalWithWCFor
#> 1              <NA>
#> 2              <NA>
#> 3              <NA>
#> 4              <NA>
#> 5             state
#> 6            county

# List the variable groups available in the 5-year 2020 American Community Survey.
acs_groups <- listCensusMetadata(
  name = "acs/acs5",
  vintage = 2020,
  type = "groups")
 head(acs_groups)
#>     name
#> 1 B17015
#> 2 B18104
#> 3 B17016
#> 4 B18105
#> 5 B17017
#> 6 B18106
#>                                                                                                                                                         description
#> 1 POVERTY STATUS IN THE PAST 12 MONTHS OF FAMILIES BY FAMILY TYPE BY SOCIAL SECURITY INCOME BY SUPPLEMENTAL SECURITY INCOME (SSI) AND CASH PUBLIC ASSISTANCE INCOME
#> 2                                                                                                                                SEX BY AGE BY COGNITIVE DIFFICULTY
#> 3                                                      POVERTY STATUS IN THE PAST 12 MONTHS OF FAMILIES BY FAMILY TYPE BY WORK EXPERIENCE OF HOUSEHOLDER AND SPOUSE
#> 4                                                                                                                               SEX BY AGE BY AMBULATORY DIFFICULTY
#> 5                                                                                      POVERTY STATUS IN THE PAST 12 MONTHS BY HOUSEHOLD TYPE BY AGE OF HOUSEHOLDER
#> 6                                                                                                                                SEX BY AGE BY SELF-CARE DIFFICULTY
#>                                                     variables       universe 
#> 1 http://api.census.gov/data/2020/acs/acs5/groups/B17015.json          FAMILY
#> 2 http://api.census.gov/data/2020/acs/acs5/groups/B18104.json NONINST_05_OVER
#> 3 http://api.census.gov/data/2020/acs/acs5/groups/B17016.json          FAMILY
#> 4 http://api.census.gov/data/2020/acs/acs5/groups/B18105.json NONINST_05_OVER
#> 5 http://api.census.gov/data/2020/acs/acs5/groups/B17017.json           HSHLD
#> 6 http://api.census.gov/data/2020/acs/acs5/groups/B18106.json NONINST_05_OVER
# Create a data dictionary with all variable names and encoded values for
# a microdata API.
cbp_dict <- listCensusMetadata(
  name = "cbp",
  vintage = 2020,
  type = "variables",
  include_values = TRUE)
 head(cbp_dict)
#>        name                                      label
#> 1       for               Census API FIPS 'for' clause
#> 2        in                Census API FIPS 'in' clause
#> 3     ucgid Uniform Census Geography Identifier clause
#> 4     EMP_N        Noise range for number of employees
#> 5     STATE                                  Geography
#> 6 PAYQTR1_N      Noise range for first-quarter payroll
#>                                                                                                                                                                                     concept
#> 1                                                                                                                                                        Census API Geography Specification
#> 2                                                                                                                                                        Census API Geography Specification
#> 3                                                                                                                                                        Census API Geography Specification
#> 4 All Sectors: County Business Patterns, including ZIP Code Business Patterns, by Legal Form of Organization and Employment Size Class for the U.S., States, and Selected Geographies: 2020
#> 5                                                                                                                                                                                      <NA>
#> 6 All Sectors: County Business Patterns, including ZIP Code Business Patterns, by Legal Form of Organization and Employment Size Class for the U.S., States, and Selected Geographies: 2020
#>   predicateType     group limit predicateOnly hasGeoCollectionSupport
#> 1      fips-for       N/A     0          TRUE                    <NA>
#> 2       fips-in       N/A     0          TRUE                    <NA>
#> 3         ucgid       N/A     0          TRUE                    TRUE
#> 4           int CB2000CBP     0          <NA>                    <NA>
#> 5          <NA>       N/A     0          <NA>                    <NA>
#> 6           int CB2000CBP     0          <NA>                    <NA>
#>    attributes required values_code values_label
#> 1        <NA>     <NA>        <NA>         <NA>
#> 2        <NA>     <NA>        <NA>         <NA>
#> 3        <NA>     <NA>        <NA>         <NA>
#> 4     EMP_N_F     <NA>        <NA>         <NA>
#> 5        <NA>     <NA>        <NA>         <NA>
#> 6 PAYQTR1_N_F     <NA>        <NA>         <NA>

# List the value labels of the NAICS2017 variable in the 2020 County
# Business Patterns dataset.
cbp_naics_values <- listCensusMetadata(
  name = "cbp",
  vintage = 2020,
  type = "values",
  variable = "NAICS2017")
 head(cbp_naics_values)
#>     code                                      label
#> 1     00                      Total for all sectors
#> 2 000000                             Industry total
#> 3     11 Agriculture, forestry, fishing and hunting
#> 4    111                            Crop production
#> 5   1111                  Oilseed and grain farming
#> 6  11111                            Soybean farming

# List of variables that are included in the B17020 group in the
# 5-year American Community Survey.
group_B17020 <- listCensusMetadata(
  name = "acs/acs5",
  vintage = 2017,
  type = "variables",
  group = "B17020")
 head(group_B17020)
#>           name
#> 1 B17020_017EA
#> 2 B17020_016MA
#> 3 B17020_016EA
#> 4 B17020_015MA
#> 5 B17020_015EA
#> 6 B17020_014EA
#>                                                                                                          label
#> 1     Annotation of Estimate!!Total!!Income in the past 12 months at or above poverty level!!85 years and over
#> 2 Annotation of Margin of Error!!Total!!Income in the past 12 months at or above poverty level!!75 to 84 years
#> 3        Annotation of Estimate!!Total!!Income in the past 12 months at or above poverty level!!75 to 84 years
#> 4 Annotation of Margin of Error!!Total!!Income in the past 12 months at or above poverty level!!60 to 74 years
#> 5        Annotation of Estimate!!Total!!Income in the past 12 months at or above poverty level!!60 to 74 years
#> 6        Annotation of Estimate!!Total!!Income in the past 12 months at or above poverty level!!18 to 59 years
#>                                       concept predicateType  group limit
#> 1 POVERTY STATUS IN THE PAST 12 MONTHS BY AGE        string B17020     0
#> 2 POVERTY STATUS IN THE PAST 12 MONTHS BY AGE        string B17020     0
#> 3 POVERTY STATUS IN THE PAST 12 MONTHS BY AGE        string B17020     0
#> 4 POVERTY STATUS IN THE PAST 12 MONTHS BY AGE        string B17020     0
#> 5 POVERTY STATUS IN THE PAST 12 MONTHS BY AGE        string B17020     0
#> 6 POVERTY STATUS IN THE PAST 12 MONTHS BY AGE        string B17020     0
#>   predicateOnly
#> 1          TRUE
#> 2          TRUE
#> 3          TRUE
#> 4          TRUE
#> 5          TRUE
#> 6          TRUE
# }