Americas Health Rankings Logo

America's Health Rankings API

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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

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

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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
name
String!

The name of the population category.

populationCategoryId
ID!

The ID of the population category.

populations
[Population!]!

The populations associated with each category.

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

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