Type: Package
Title: Programmatic Access to County Health Rankings & Roadmaps Data
Version: 0.1.3
Maintainer: Hannah Olson-Williams <hannaheow@gmail.com>
Description: Provides a simple interface to pull County Health Rankings & Roadmaps (CHR&R) county-level health data and metadata directly from 'Zenodo' <doi:10.5281/zenodo.18157681>. Users can retrieve data for CHR&R release years 2010 through 2025. CHR&R data support research and decision-making to promote health equity and policies that help all communities thrive.
License: GPL (≥ 3)
Encoding: UTF-8
RoxygenNote: 7.3.3
URL: https://github.com/County-Health-Rankings-and-Roadmaps/countyhealthR
BugReports: https://github.com/County-Health-Rankings-and-Roadmaps/countyhealthR/issues
Imports: dplyr, magrittr, readr, httr, stringr, jsonlite, rappdirs, curl, rlang
Suggests: testthat, knitr, rmarkdown, covr
VignetteBuilder: knitr
Depends: R (≥ 3.5)
NeedsCompilation: no
Packaged: 2026-02-21 05:15:41 UTC; holsonwillia
Author: Hannah Olson-Williams [aut, cre]
Repository: CRAN
Date/Publication: 2026-02-25 19:20:02 UTC

Get County-Level County Health Rankings & Roadmaps Data

Description

Returns County Health Rankings & Roadmaps (CHR&R) measure data for a specified state and (optionally) county and release year. Data are retrieved from the Zenodo repository and include measure values and associated metadata.

Usage

get_chrr_county_data(
  state,
  county = NULL,
  release_year = NULL,
  refresh = FALSE,
  citation = TRUE,
  verbose = TRUE
)

Arguments

state

Character. Specifies the state. May be a full state name (e.g., "Wisconsin"), postal abbreviation (e.g., "WI"), or two-digit FIPS code (e.g., "55").

county

Character. Specifies the county. May be a county name (e.g., "Dane") or a three-digit county FIPS code (e.g., "025"). Matching is not case sensitive and ignores common suffixes such as "County," "Parish," "City," "Borough," or similar. If missing, NA, or "000", state-level data are returned.

release_year

Numeric. Specifies the CHR&R release year. Defaults to the most recent available release year.

refresh

Logical. Indicates whether to force a fresh download from Zenodo even if cached data are available. Defaults to FALSE.

citation

Logical. If TRUE (default), prints the appropriate Zenodo DOI for the requested release year which is useful for citation. Set to FALSE to suppress DOI output.

verbose

Logical. If TRUE (default), additional information about the selected geography is displayed. Set to FALSE to return only the requested data.frame.

Details

If a county is specified, county-level data are returned. If the county argument is missing, NA, or "000", state-level data are returned instead.

Value

A tibble (class tbl_df, tbl, data.frame) containing CHR&R measure values for the specified geography and release year.

For county-level requests, the tibble includes one row per measure for the specified county and contains the following columns:

state_fips

Character. Two-digit state FIPS code.

county_fips

Character. Three-digit county FIPS code.

measure_id

Character. Unique CHR&R measure identifier.

measure_name

Character. Measure name.

description

Character. Brief measure description.

raw_value

Numeric. Reported measure value.

ci_low

Numeric. Lower bound of confidence interval, if available.

ci_high

Numeric. Upper bound of confidence interval, if available.

numerator

Numeric. Measure numerator, if available.

denominator

Numeric. Measure denominator, if available.

years_used

Character. Years used in calculation of the measure.

compare_years_text

Character. Text describing temporal comparison.

compare_states_text

Character. Text describing state comparison.

For state-level requests, the structure is identical except that county_fips is not included.

The returned tibble represents the full set of CHR&R measures available for the specified geography and release year.

Examples


# County-level example
dane <- get_chrr_county_data("WI", "Dane", 2024)
head(dane)

# State-level example
wi <- get_chrr_county_data("WI", county = NULL, 2024)
head(wi)

Retrieve County Health Rankings & Roadmaps measure data from 'Zenodo'

Description

Downloads and filters County Health Rankings & Roadmaps (CHR&R) data directly from the 'Zenodo' archive (doi:10.5281/zenodo.18157681). Users provide the measure ID, geography type, and release year as inputs. The function returns data for the specified measure across the specified geography for the given release year. It mimics the style and behavior of tidycensus::get_decennial().

Usage

get_chrr_measure_data(
  geography = c("county", "state", "national"),
  measure,
  release_year = NULL,
  refresh = FALSE,
  citation = TRUE,
  verbose = TRUE
)

Arguments

geography

A string specifying the level of geography to return. Options are:

  • "county" – returns all county-level estimates.

  • "state" – returns all state-level estimates (excluding national).

  • "national" – returns only national-level estimates (state_fips == "00").

measure

Either:

  • A numeric measure_id (e.g., 21, 85, etc.), or

  • A character string matching a measure_name (case-insensitive).

Use the list_chrr_measures() function to print all available measure_ids and measure_names for a given release year.

release_year

Numeric. Specifies the CHR&R release year to pull data. Defaults to the most recent release year.

refresh

Logical. If TRUE, forces re-download of data even if a cached version is available. Defaults to FALSE.

citation

Logical. If TRUE (default), prints the appropriate Zenodo DOI for the requested release year which is useful for citation. Set to FALSE to suppress DOI output.

verbose

Logical. If TRUE (default), additional information about the selected measure is displayed including the measure name and selected metadata fields. Set to FALSE to return only the requested data.frame.

Value

A tibble (class tbl_df, tbl, data.frame) containing CHR&R data for the specified measure, geography, and release year.

The tibble contains one row per geographic unit and includes:

state_fips

Character. Two-digit state FIPS code.

county_fips

Character. Three-digit county FIPS code. Present only for county-level data.

raw_value

Numeric. Reported measure value.

numerator

Numeric. Measure numerator, if available.

denominator

Numeric. Measure denominator, if available.

ci_low

Numeric. Lower confidence interval bound, if available.

ci_high

Numeric. Upper confidence interval bound, if available.

The returned tibble represents the full set of observations for the requested measure at the specified geographic level and release year.

Examples


# Get county-level data for measure 21 (high school graduation) in 2023
county_data <- get_chrr_measure_data(
                  geography = "county",
                  measure = 21,
                  release_year = 2023)

# Get state-level data for "Insufficient Sleep" in 2022
state_data <- get_chrr_measure_data(
                  geography = "state",
                  measure = "insufficient sleep",
                  release_year = 2022)

# Get national-level data for "Uninsured" in 2024
nat_data <- get_chrr_measure_data(
                  geography = "national",
                  measure = "uninsured",
                  release_year = 2024)

Get Metadata for a County Health Rankings & Roadmaps Measure

Description

Returns structured metadata for a County Health Rankings & Roadmaps (CHR&R) measure for a given release year. The metadata describes the measure's position within the CHR&R Model of Health, which has evolved over time: releases prior to 2025 follow the legacy model, while 2025 and later releases use the new model of health. Metadata is year-specific, reflecting the measure definitions and groupings used in that release.

Usage

get_chrr_measure_metadata(measure, release_year = NULL)

Arguments

measure

A character specifying the measure. Can be either a measure_id or measure_name.

release_year

A numeric specifying the release year for which to pull the metadata. Defaults to the most recent release year if NULL.

Value

A tibble (class tbl_df, tbl, data.frame) containing one row of metadata for the requested measure.

Columns include:

year

Numeric. CHR&R release year.

measure_id

Numeric. Unique identifier for the measure.

measure_name

Character. Official name of the measure.

description

Character. Text description of the measure definition.

years_used

Character. Data years used in calculating the measure.

factor_name

Character. Top-level grouping in the CHR&R model.

category_name

Character. Category within factor.

focus_area_name

Character. Focus area within category.

direction

Numeric. Indicates score orientation: 1 = higher values are worse, -1 = higher values are better.

display_precision

Numeric. Recommended number of decimal places for reporting values.

format_type

Numeric. Suggested display format code: 0 = rate, 1 = percentage, 2 = dollars, 3 = ratio, other values reserved for internal codes.

compare_states_text

Character. Notes about comparability across states.

compare_years_text

Character. Notes about comparability across release years.

Examples


# Return metadata
md <- get_chrr_measure_metadata(21, 2024)
md$display_precision
md$format_type
md$direction
md$compare_states_text

List available CHR&R measures for a given release year

Description

Downloads metadata for a release year and returns measure identifiers, names, and descriptions.

Usage

list_chrr_measures(release_year = NULL)

Arguments

release_year

Numeric year corresponding to the year of CHR&R's annual data release. Defaults to the most recent release year if NULL.

Value

A tibble (class tbl_df) with one row per measure for the specified release year and the following columns:

measure_id

Numeric. Unique identifier for the measure.

measure_name

Character. Name of the measure.

description

Character. Brief description of the measure.

Examples


measures <- list_chrr_measures(2023)
head(measures)