America's Health Rankings API

Topics

Welcome About the Beta (v1 Beta)Getting Started Sources & Citations

Overview

Welcome

Welcome to America's Health Rankings API documentation.

About the Beta (v1 Beta)

The United Health Foundation is launching this America’s Health Rankings API in beta for users to test and provide feedback before the full release. Please register for a key and submit your feedback or commentary through our Feedback form.

Getting Started

Get started by getting an API key. Use the form to register and request an API key. Your API key will be emailed to you.

Once you have your API key, you'll need to set it to an http header: x-api-key for every request to the API server.

Keep your key private. Only use it for server to server communication. Here is an example node.js fetch request, which adds the key privately:

// run in node.js
const fetchAHR = async (query, vars) => {
  const res = await fetch("https://api.americashealthrankings.org/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.AHR_API_KEY,
    },
    body: JSON.stringify({
      query,
      variables: vars,
    }),
  });
  return res.json();
};

fetchAHR(`
  query ExampleQuery {
    measures_A {
      measureId
      name
    }
    measures_B {
      measureId
      name
    }
  }
`);

Sources & Citations

Please remember, it is always required to cite America’s Health Rankings and the date accessed when utilizing and displaying data acquired through the America’s Health Rankings Data API.

Source information has two elements and can be found in two places:

Measure Sources: Each "Health Measure" provided through the API carries a "source" property. This includes the "name" of the source from which data is accessed (i.e., CDC’s Behavioral Risk Factor Surveillance System).
MeasureDatum Source Dates: Each "data-point" attributed to a health measure will carry information about the time period from which the data was collected. Use the "dateLabel" property to display this time period.

Please also include the Source Name of the Health Measure and if applicable, a Date Label of the Data you have referenced.

Example: America's Health Rankings analysis of CDC, Behavioral Risk Factor Surveillance System, United Health Foundation, AmericasHealthRankings.org, accessed 2023.

Examples

Measures Query

Get measures with populations and sources:

This query:

query measures {
  measures_A {
    measureId
    name
    description
    format
    precision
    unitType
    isWeightPositive
    population {
      name
    }
    source {
      name
    }
  }
}

Will return data like:

{
  "measureId": "152",
  "name": "Smoking",
  "description": "Percentage of adults who reported smoking at least 100 cigarettes in their lifetime and currently smoke daily or some days (pre-2011 BRFSS methodology)",
  "format": "Percent",
  "precision": 1,
  "unitType": "Percentage of adults",
  "isWeightPositive": "N",
  "population": {
    "name": null
  },
  "source": {
    "name": "CDC, Behavioral Risk Factor Surveillance System"
  }
}

Data Queries

You can use the measuresId (aka: metricId) to grab associated information for that measure:

Example:

query measure($metricId: Int!) {
  measure_A(metricId: $metricId) {
    name
    description
    format
    precision
    unitType
    isWeightPositive
    data(where: { state: { eq: "NY" } }) {
      dateLabel
      endDate
      lowerCI
      measureDatumId
      rank
      startDate
      state
      upperCI
      value
    }
  }
}

This is the same as the above, but uses the "in" operator to pull a bit more data:

query measure($metricId: Int!) {
  measure_A(metricId: $metricId) {
    name
    description
    format
    precision
    unitType
    isWeightPositive
    data(where: { state: { in: ["NY", "ME", "MA", "CT", "NH"] } }) {
      dateLabel
      endDate
      lowerCI
      measureDatumId
      rank
      startDate
      state
      upperCI
      value
    }
  }
}

Reference

Queries

Data Sets

Our offering of Health Measures and Data comprises multiple Data Sets with unique contents. While they share an identical Query structure, the input parameters supported by each Data Set’s Queries differ.

Data sets are denoted by a suffix, eg. data_A and data_B, measures_A, and measures_B.

data_A

Type: [MeasureDatum!]!

This query will return a collection of data points. Data can be limited to a specific state. For querying data associated with one or more specific health measures, use the “measures” query.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

data_B

Type: [MeasureDatum!]!

This query will return a collection of data points. Data can be limited to a specific state. For querying data associated with one or more specific health measures, use the “measures” query.

Arguments

Name	Description
skip `Int`	The number of items you would like to skip, useful for pagination of large data sets.
state `String`	A U.S. state postal code. Eg. “NY”. For national data use, “ALL”.
take `Int`	The number of items you would like to retrieve, useful for pagination of large data sets.

datum_A

Type: MeasureDatum

This query will return an individual data point. Data can be limited to a specific state. For querying data associated with one or more specific health measures, use the “measures” query.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

datum_B

Type: MeasureDatum

This query will return an individual data point. Data can be limited to a specific state. For querying data associated with one or more specific health measures, use the “measures” query.

Arguments

Name	Description
measureDatumId `Int`	The id of an individual data record.

measure_A

Type: Measure

This query will return an individual measure. You must provide a “measureId” argument to specify which measure you are seeking.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

measure_B

Type: Measure

This query will return an individual measure. You must provide a “measureId” argument to specify which measure you are seeking.

Arguments

Name	Description
measureId `Int!`	The id of an individual measure.

measures_A

Type: [Measure!]!

This query will return a collection of measures. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

measures_B

Type: [Measure!]!

This query will return a collection of measures. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
skip `Int`	The number of items you would like to skip, useful for pagination of large data sets.
take `Int`	The number of items you would like to retrieve, useful for pagination of large data sets.

population_A

Type: Population

This query will return an individual population. You must provide a “populationId” argument to specify which population you are seeking.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

population_B

Type: Population

This query will return an individual population. You must provide a “populationId” argument to specify which population you are seeking.

Arguments

Name	Description
populationId `Int`	The id of an individual population.

populationCategories_A

Type: [PopulationCategory!]!

This query will return a collection of population categories. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

populationCategories_B

Type: [PopulationCategory!]!

This query will return a collection of population categories. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
skip `Int`	The number of items you would like to skip, useful for pagination of large data sets.
take `Int`	The number of items you would like to retrieve, useful for pagination of large data sets.

populationCategory_B

Type: PopulationCategory

This query will return an individual population category, such as “Age”. You must provide a “populationCategoryId” argument to specify which population category you are seeking.

Arguments

Name	Description
populationCategoryId `Int`	The id of an individual population category.

populations_A

Type: [Population!]!

This query will return a collection of populations. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

populations_B

Type: [Population!]!

This query will return a collection of populations. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
skip `Int`	The number of items you would like to skip, useful for pagination of large data sets.
take `Int`	The number of items you would like to retrieve, useful for pagination of large data sets.

report_A

Type: Report_A

Arguments

Name	Description
editionId `Int!`

report_B

Type: Report

This query will return an individual report. You must provide a “reportId” argument to specify which report you are seeking.

Arguments

Name	Description
reportId `Int!`	The id of an individual report.

reports_A

Type: [Report_A]

Arguments

Name	Description
order `[ReportSortInput_A!]`
where `ReportFilterInput_A`

reports_B

Type: [Report!]!

This query will return a collection of reports. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
skip `Int`	The number of items you would like to skip, useful for pagination of large data sets.
take `Int`	The number of items you would like to retrieve, useful for pagination of large data sets.

reportTypes_A

Type: [ReportType_A]

Arguments

Name	Description
order `[ReportTypeSortInput_A!]`
where `ReportTypeFilterInput_A`

source_A

Type: Source

This query will return an individual data source. You must provide a “sourceId” argument to specify which population category you are seeking.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

source_B

Type: Source

This query will return an individual data source. You must provide a “sourceId” argument to specify which population category you are seeking.

Arguments

Name	Description
sourceId `Int`	The id of an individual source.

sources_A

Type: [Source!]!

This query will return a collection of data sources. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
where	Specifies filtering conditions as an object that includes the field to filter and the filter criteria.

sources_B

Type: [Source!]!

This query will return a collection of data sources. Use the “skip” and “take” parameters to paginate the data.

Arguments

Name	Description
skip `Int`	The number of items you would like to skip, useful for pagination of large data sets.
take `Int`	The number of items you would like to retrieve, useful for pagination of large data sets.

Objects

Measure

Measures from the America’s Health Rankings platform that are indicators of or associated with population health.

Fields

Name	Description
data `[MeasureDatum!]!`	The data points for the measure.
description `String!`	The description of the measure.
format `String`	The value type of the measure data value field, such as “Percent”, “Currency”, or “Numeric”.
isWeightPositive `String`	Indicates a positive association with health. For example, the measure ‘Exercise’ would return the value “Y” while Smoking would return the value “N”.
measureId `ID!`	The ID unique to the measure. Measures with the same ID are comparable over time.
name `String!`	The name of the measure.
population `Population!`	The population that the measure is for, such as “Hispanic” or “Ages 18-24”.
precision `Int!`	The precision of the measure data value field, indicating how many decimal places data should be displayed.
source `Source`	The original source of the measure's data.
subpopulations `[Measure!]!`	Measures pertaining to slices of the population - subpopulations. Only "root" measures have subpopulations. Note that some subpopulations are treated as root measures in this data set if they are featured in Health of Women and Children or Senior reports.
unitType `String!`	The description of the measure’s units, typically a shortened version of description. For example, “Deaths per 100,000 population.”

MeasureDatum

The data points for a measure.

Fields

Name	Description
dataNotes `[DataNote!]`	Information relevant to the MeasureDatum for instances in which data is not available, suppressed, or has other nuances to be taken into account.
dateLabel `String!`	The date or time period from which the data is from.
endDate `Date`	The end date of the time period of the data. For data from a given year, endDate is set to “1/1/YYYY”. This field is useful for handling date ranges (i.e., startDate - endDate).
lowerCI `Float`	The lower 95% confidence interval, where available. Not all measures or data years for a specific measure have confidence intervals available.
measure `Measure!`	The name of the measure.
measureDatumId `ID!`	The ID unique to each data.
rank `Int`	The rank of each state’s value by healthiest (1) to least healthy (50).
startDate `Date`	The start date of the time period of the data. For data from a given year, startDate is set to “1/1/YYYY”. This field is useful for handling date ranges (i.e., startDate - endDate).
state `String`	The two-letter postal code of a state. Note the United States value is labeled as “ALL”.
upperCI `Float`	The upper 95% confidence interval, where available.
value `Float`	The value for a given measure, state, and data year.

Population

Population describes which segment of the population the measure is describing such as “Hispanic” or “Ages 18-24”. This is a property of subpopulations only.

Fields

Name	Description
measures `[Measure!]!`	The name of the measure.
name `String!`	The name of the population.
populationCategory `PopulationCategory!`	The category of the population group, such as “Race” or “Age”.
populationId `ID!`	The ID of the population.

PopulationCategory

The Population Category organizes populations into categories such as race, age, gender, income, and education.

Fields

Name	Description
name `String!`	The name of the population category.
populationCategoryId `ID!`	The ID of the population category.
populations `[Population!]!`	The populations associated with each category.

Report

Fields

Name	Description
liveOn `Date!`	The Report publish date
measures `[Measure!]!`
name `String!`	The name of the report
reportId `ID!`	The ID of the Report
reportType `String!`	The type of report
slug `String!`

Report_A

Fields

Name Description

name
String

releaseDate
Int!

reportId
Int!

reportMeasures
[ReportMeasureType_A]

Arguments

Name	Description
order `[ReportMeasureTypeSortInput_A!]`
where `ReportMeasureTypeFilterInput_A`

reportType
ReportType_A

reportTypeId
Int!

ReportMeasureType_A

Fields

Name Description

endDate
DateTime_A

measure
Measure_A

Arguments

Name	Description
order `[MeasureSortInput_A!]`
where `MeasureFilterInput_A`

measureId
Int!

report
Report_A

Arguments

Name	Description
order `[ReportSortInput_A!]`
where `ReportFilterInput_A`

reportId
Int!

ReportType_A

Fields

Name Description

name
String

reportTypeId
Int!

reports
[Report_A]

Arguments

Name	Description
order `[ReportSortInput_A!]`
where `ReportFilterInput_A`

Source

The primary Source of the data. All data presented on the America’s Health Rankings platform is secondary data, except for the ‘state rankings’ index measures.

Fields

Name	Description
measures `[Measure!]!`	The name of the measure.
name `String!`	The name of the original data source.
sourceId `ID!`	The ID of the source.

Scalars

Boolean

TheBoolean scalar type represents true or false.

Date

Date custom scalar type

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.