Tools

Four tools for discovering and querying CDC public health data. Three query the CDC Open Data portal (Socrata); one queries CDC WONDER mortality statistics:

cdc_discover_datasets

Search the CDC dataset catalog to find relevant datasets.

• Full-text search across dataset names and descriptions
• Filter by domain category (e.g., "NNDSS", "Vaccinations", "Behavioral Risk Factors")
• Filter by domain tags (e.g., ["covid19", "surveillance"]) — a dataset matches on any one tag, so each tag added widens the result set; narrow with query or category, which intersect with the tag set
• Returns dataset IDs, names, truncated descriptions, a column count with a short column sample, and update timestamps — use cdc_get_dataset_schema for the full column list
• Each result carries its catalog assetType (dataset, filter, chart, map, story, file, href); a columnCount of 0 marks an entry that is not tabular and yields no data from the other tools
• Pagination via offset for browsing large result sets — offset plus limit must not exceed 10,000, the ceiling the catalog enforces
• domain selects the host contacted, data.cdc.gov (default) or chronicdata.cdc.gov — both front the same catalog and return the same entries, so switching hosts neither widens nor narrows a search

cdc_get_dataset_schema

Fetch the column schema for a specific dataset.

• Column names, data types, and full descriptions — never truncated per column
• Row count and last-updated timestamp
• Essential for understanding column types before writing $where clauses
• Accepts four-by-four dataset identifiers (e.g., bi63-dtpu)
• Returns the first 100 columns by default. Catalog schemas run from 3 to 322 columns, so every ordinary dataset arrives whole; wider ones report totalCount, truncated, and a nextOffset to pass back as column_offset. Raise column_limit (max 500) to pull a wide schema in one call
• A column_offset at or past the column count returns an empty window rather than an error
• Fails with not_queryable when the ID names a non-tabular catalog asset, rather than returning an empty column list
• domain selects the host contacted, data.cdc.gov (default) or chronicdata.cdc.gov — a four-by-four ID resolves on either

cdc_query_dataset

Execute SoQL queries against any CDC dataset.

• Full SoQL support: $select, $where, $group, $having, $order
• Full-text search across all text columns via $q
• Up to 5,000 rows per request with pagination
• truncated is measured, not guessed: the request fetches one row past the limit and drops it, so a page that fills the limit exactly is reported as complete instead of sending you paginating an aggregate
• nextOffset names where to resume whenever rows remain. Pair it with an order clause — SODA does not order results implicitly, and order=":id" works on any dataset
• Rows are also bounded by a 200,000-character response budget, so a wide dataset at limit: 5000 returns a usable page with a nextOffset rather than several megabytes
• Returns the SoQL clauses it sent as effectiveQuery, values in their original text rather than URL-encoded, so a clause can be copied back into the parameter it came from
• All response values are strings (per SODA v2.1) — parse based on column type metadata
• domain selects the host contacted, data.cdc.gov (default) or chronicdata.cdc.gov — a four-by-four ID returns the same rows from either

cdc_query_wonder

Query CDC WONDER for national US mortality statistics — a separate CDC system from the Socrata datasets the other tools query.

database picks which of CDC's five mortality databases answers the query: