CDC Open Data API

Free CDC Open Data API with no key: hundreds of public health datasets — mortality, life expectancy, chronic disease, environmental health — queryable with SoQL filters.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the CDC Open Data API?

CDC Open Data is a free, key-free Socrata-powered API exposing hundreds of US public health datasets. Each dataset has its own four-by-four identifier and endpoint, and supports SoQL query parameters for filtering, aggregation, sorting and paging without downloading the whole file.

Every dataset the CDC publishes gets a Socrata endpoint, and the pattern never varies: `data.cdc.gov/resource/{id}.json` where the id is an eight-character code like `w9j2-ggv5`. The example returns US life expectancy and mortality by year, race and sex from 1900 onwards — the kind of long time series that would otherwise mean downloading a spreadsheet and parsing it by hand.

The SoQL layer is what elevates this above a file download. `$where`, `$select`, `$group`, `$order` and `$limit` let you aggregate server-side, so a question like average life expectancy by decade becomes one URL rather than a local analysis. Two consistent traps: every value comes back as a string, including numbers and years, so cast before arithmetic; and the default `$limit` is 1000, which silently truncates larger datasets. Note also that these are official statistics with real methodological caveats — suppressed small counts, revised historical figures, changing race and ethnicity categories over a 120-year series — documented on each dataset's landing page rather than in the API response.

Quick facts

Base URL: https://data.cdc.gov/resource
Authentication: No API key required, though a free Socrata app token raises the anonymous rate limit and is sent in an `X-App-Token` header. CDC data is US government work in the public domain.
Rate limit: Anonymous requests share a per-IP throttle; a free app token gives you a much higher dedicated allowance. Neither requires payment.
Pricing: Free, public domain.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the CDC Open Data API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Fetch US life expectancy and mortality by year

GET https://data.cdc.gov/resource/w9j2-ggv5.json?$limit=2

curl

curl 'https://data.cdc.gov/resource/w9j2-ggv5.json?$limit=2'

JavaScript (fetch)

const res = await fetch("https://data.cdc.gov/resource/w9j2-ggv5.json?$limit=2");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://data.cdc.gov/resource/w9j2-ggv5.json?$limit=2", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200

[
  {
    "year": "1900",
    "race": "All Races",
    "sex": "Both Sexes",
    "average_life_expectancy": "47.3",
    "mortality": "2518.0"
  },
  {
    "year": "1901",
    "race": "All Races",
    "sex": "Both Sexes",
    "average_life_expectancy": "49.1",
    "mortality": "2473.1"
  }
]

Parameters

Parameter	Type	Required	Description
`(dataset id)`	path segment	Required	The dataset's four-by-four identifier, plus a format extension. `w9j2-ggv5.json`
`$limit`	query	Optional	Rows to return. Defaults to 1000, which silently truncates larger datasets. `2`
`$offset`	query	Optional	Zero-based offset for paging. `0`
`$select`	query	Optional	Columns to return, and aggregate expressions such as `avg(mortality)`. `year,average_life_expectancy`
`$where`	query	Optional	SoQL filter expression, using SQL-like comparison and boolean operators. `year > '2000'`
`$group`	query	Optional	Group-by clause for server-side aggregation, paired with `$select`. `race`
`$order`	query	Optional	Sort specification; append `DESC` to reverse. `year DESC`
`$q`	query	Optional	Full-text search across the whole row. `diabetes`

Response fields

(array of row objects)array: The response is a bare JSON array of rows; column names come from the dataset, not a fixed schema.
yearstring: Year as a string. Every Socrata value is a string, including numbers — cast before comparing or sorting numerically.
race / sexstring: Demographic breakdown columns. Categories change across a long time series, so do not assume they are stable.
average_life_expectancystring: The measure value, again as a string.
mortalitystring: Age-adjusted death rate per 100,000 in this dataset. Column meanings vary per dataset — read the landing page.
(X-SODA2-* headers)header: Socrata metadata headers accompany the response, including field type information.

What you can build with the CDC Open Data API

Chart a long-run public health indicator such as life expectancy
Aggregate mortality data by state or demographic group server-side
Feed official statistics into a research dashboard
Track chronic disease prevalence over time
Download a filtered slice of a large dataset instead of the whole file

Common errors and how to fix them

Only 1000 rows returned

That is the default `$limit`.

Fix: Set `$limit` explicitly and page with `$offset`, or aggregate server-side with `$group` so you never need the raw rows.

Numbers sorting incorrectly

All values are strings.

Fix: Cast in your code, or use SoQL's typed functions in `$where` and `$order` so the comparison happens server-side.

400 on a $where clause

SoQL is not quite SQL.

Fix: String literals take single quotes and the function set is limited. Test the expression in the dataset's Socrata explorer first.

429

Anonymous per-IP throttle exceeded.

Fix: Request a free Socrata app token and send it as `X-App-Token`. It costs nothing and lifts the limit substantially.

CDC Open Data API — frequently asked questions

Is the CDC Open Data API free?

Yes, free with no key, and CDC data is US government work in the public domain. A free Socrata app token is optional and simply raises the rate limit for anonymous callers.

How do I find a dataset's identifier?

Browse data.cdc.gov and open the dataset; its four-by-four code appears in the page URL and in the API endpoint the site shows you. That code plus a format extension is the whole endpoint.

Why are all the values strings?

Socrata serialises every column as a string in JSON regardless of its declared type. Cast in your own code, or push comparisons and sorting into SoQL parameters where the platform applies the correct types server-side.

Can I trust these figures directly?

They are official statistics, but each dataset carries methodological caveats — suppressed small counts, retrospective revisions, and demographic categories that change across long time series. Those caveats live on the dataset landing page, not in the API response, so read it before publishing conclusions.

Tools that pair with this API

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

CSV Column Statistics Calculator

Profile a CSV column by column: type, blanks, distinct values, min, max, mean, median, standard deviation and percentiles, plus top values — all in-browser.

CSV Filter

Filter CSV rows online by column conditions — equals, contains, regex, empty, numeric ranges — combined with AND/OR. Keep or remove matches, fully in-browser.

CDC Open Data is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.