Pulse

pulse is a command line tool for querying public health data. It covers nine live sources: CDC WONDER, NCI SEER cancer statistics, CDC Open Data, the NCHS Data Query System (Health, United States), WISQARS injury data, ATSDR GRASP disease surveillance, NSSP ED visits, NIS vaccination surveys, and SUDORS fatal-overdose surveillance. Browse them by topic, run bundled queries, and get CSV, JSON, or a table back.

Setup

# From PyPI (requires Python 3.11+)
pip install pulse-code
pulse --help

# From uv in this local directory
uv run pulse --help

Querying any of the nine sources needs no API key or login. The build, query, refine, compare, and chat commands call an LLM to write CDC WONDER XML for you, so those need a key:

export ANTHROPIC_API_KEY=sk-ant-...

Azure OpenAI and proxied connections work too; see docs/llm-providers.md.

Usage

Five top level commands. topics browses by subject across all sources, source browses and queries one source, search is free text find, doctor checks credentials and source reachability, and generate writes a health-style fetch_*.py starter script from a saved query.

Start with a subject if you don't know which source holds what you want:

pulse topics                                         # every subject across all nine sources
pulse topics mortality                               # drill into one
pulse search "opioid overdose deaths by state"
pulse search "tick-borne disease cases" --queries    # queries only
pulse search "recent COVID deaths" --datasets        # datasets only

Or go straight at a source. Each one nests the same way:

pulse source                      # what sources exist
pulse source seer                 # what that source offers
pulse source seer mortality       # query it

pulse source wonder: CDC WONDER

pulse source wonder datasets      # 26+ datasets
pulse source wonder info D176     # provisional mortality
pulse source wonder run drug-deaths-by-year-2018-2024-req.xml -f csv
pulse source wonder query "fentanyl deaths by state 2020-2024" -f csv

Mortality, natality, VAERS, and environmental datasets going back to 1968, with 59 bundled XML queries and LLM-backed commands that write new ones. CDC requires 15 seconds between queries. Full command reference and the dataset table: docs/cdc-wonder.md.

pulse source seer: NCI SEER Cancer Statistics

pulse source seer sites --search breast              # look up a cancer site code
pulse source seer mortality --site 55 --sex female -f csv
pulse source seer mortality --site 47 --compare-by race -f csv
pulse source seer incidence --site 55 --stage 104 -f csv
pulse source seer by-age --site 1 -f csv
pulse source seer compare-sites 55 47 66 -f csv      # breast vs. lung vs. melanoma

Cancer incidence and U.S. mortality rates and counts by site, sex, race, and age group, back to 1975. Calls the same unauthenticated JSON endpoints SEER*Explorer itself uses.

pulse source cdc-open: CDC Open Data (data.cdc.gov)

pulse source cdc-open list                           # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
pulse source cdc-open list --search wastewater
pulse source cdc-open query leading_death --where "year='2015'" -f csv
pulse source cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json

Raw SODA queries (--where, --select, --group, --order) against any registered Socrata dataset, by registry key or Socrata ID. Set CDC_DATA_APP_TOKEN for a higher rate limit.

pulse source dqs: NCHS Data Query System (Health, United States)

pulse source dqs list                                        # 28 datasets across 17 topics
pulse source dqs list --topic "Chronic Disease"              # filter by topic bucket
pulse source dqs list --search cholesterol
pulse source dqs trend drug-overdose-deaths -f csv           # all-persons national trend, oldest→newest
pulse source dqs trend cholesterol-adults --list-measures    # see a dataset's estimate types
pulse source dqs trend cholesterol-adults -e "mg/dL, age adjusted" -f csv
pulse source dqs query nhis-adult --where "classification='Total'" --limit 500 -f json

The unified query layer over CDC's Data Query System — the "Health, United States" report family drawn from NHANES, NHIS, NHAMCS, NVSS, NPALS, and NHCS. Every DQS topic is published as a Socrata dataset on data.cdc.gov sharing one tidy schema (topic / classification / group / subgroup / estimate_type / time_period / estimate / lci / uci), so a single query verb covers all 28. classification = 'Total' is the all-persons row; other classifications are demographic, geographic, or socioeconomic cuts. Fills in areas the other sources don't: chronic-disease and risk-factor prevalence, nutrition, oral health, disability, self-reported health, the health-care system (beds, ED visits, utilization), workforce, spending, and long-term care. Backed by the same Socrata client as cdc-open; set CDC_DATA_APP_TOKEN for a higher rate limit.

pulse source sudors: SUDORS Fatal Overdose Surveillance

pulse source sudors list                                     # 13 slices
pulse source sudors release                                  # which release this is
pulse source sudors drugs -y 2024 -j Overall -f csv          # drugs ruled as causing death
pulse source sudors drugs --detected -y 2024 -j Overall      # xylazine, nitazenes, carfentanil, bromazolam
pulse source sudors circumstances -y 2024 -j Ohio --section Bystanders
pulse source sudors demographics -y 2024 -j Ohio -d race_ethnicity
pulse source sudors months -y 2024 -j Overall --drug fentanyl -f csv
pulse source sudors trend -r "2020 to 2024" -m alldrug_rate  # the comparable series
pulse source sudors jurisdictions -y 2024

CDC's State Unintentional Drug Overdose Reporting System — death-investigation surveillance across 49 states and DC, abstracting >600 elements per death from the death certificate, the medical examiner/coroner report, and postmortem toxicology.

It answers what WONDER structurally cannot. ICD-10 puts every synthetic opioid but methadone in T40.4, so WONDER cannot separate illegally-made fentanyls from carfentanil or nitazene analogs, and xylazine and bromazolam have no code at all — SUDORS names each from toxicology. It also carries circumstances no death certificate holds: bystander present, naloxone administered, prior overdose, recent institutional release, route of use.

Two things to know. The annual Overall row is not a time series — a jurisdiction counts toward a year only if it reported every overdose death and had circumstance data on ≥75% of them, and that set changes annually (34 jurisdictions in 2020, 43 in 2024), so plotting it charts coverage as much as mortality; trend holds the jurisdiction set fixed instead. And SUDORS will not reconcile with WONDER, by design: its case definition adds a literal-text arm ("overdose", "toxicity", "intoxication") on top of X40–X44 / Y10–Y14, and it counts occurrent rather than resident deaths.

There is no SUDORS API — these commands read the public dashboard's own JSON payloads, and CDC's workbook for the trend tables. Data years 2020–2024, restated annually.

pulse source wisqars: Injury and Violence Data

pulse source wisqars list
pulse source wisqars mortality --intent Suicide --mechanism Firearm -f csv       # 1999-2016
pulse source wisqars national --intent FA_Deaths --type year -f csv              # 2019-present
pulse source wisqars state --intent Drug_OD --year 2023 -f table
pulse source wisqars county --state Texas --intent FA_Deaths --year 2023
pulse source wisqars tract --state Texas --intent All_Homicide --year 2022       # census-tract granularity
pulse source wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"

Fatal firearm, suicide, homicide, and drug overdose data from WISQARS at national, state, county, and census tract granularity, backed by the same Socrata client as cdc-open.

pulse source grasp: ATSDR GRASP Disease Surveillance

pulse source grasp list
pulse source grasp hantavirus cases --outcome Dead -f table                      # pre-1993-present
pulse source grasp hantavirus by-year -f table
pulse source grasp hantavirus by-state -f table
pulse source grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
pulse source grasp fluview ili-by-region --epiweeks 201940-202020 -f table
pulse source grasp fluview clinical-data --region nat --epiweeks 202001-202026
pulse source grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
pulse source grasp flusurv by-season --location CA -f table
pulse source grasp flusurv by-location --season 2019-20 -f table

Hantavirus cases, FluView ILINet influenza-like-illness activity, WHO/NREVSS clinical lab flu positivity, and FluSurv-NET hospitalization rates, from gis.cdc.gov/grasp and the CMU Delphi Epidata API. Repeatable options like --region and --location take one value per flag (--region nat --region ca), unlike health's argparse CLI, which accepts a space separated list after a single flag.

pulse source nssp: Emergency Department Visit Surveillance

pulse source nssp query covid --geo-type state --geo-value ca -f csv
pulse source nssp query influenza --geo-type nation --geo-value us
pulse source nssp national --start 202401 -f csv                # all 4 pathogens, national
pulse source nssp hhs rsv --region 4 -f table

Weekly percentage of ED visits attributed to COVID, flu, and RSV from the National Syndromic Surveillance Program, via the CMU Delphi Epidata API. Time values use epiweek format (YYYYWW, so 202518 is week 18 of 2025).

pulse source nis: National Immunization Survey

pulse source nis list child                                        # available years, 2011-2022
pulse source nis stream child 2022 --limit 10 -f json              # raw respondent microdata
pulse source nis rates child 2022 --vaccines P_UTD431 -f table     # state-level UTD rates
pulse source nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
pulse source nis national child 2022                               # national UTD summary

Childhood (19-35mo) and teen (13-17yr) vaccination coverage from CDC's annual random-digit-dial survey. The source files are large fixed-width .dat files (50-200MB), and pulse streams them straight through without writing anything to disk.

Two things to know. 2015 is missing from both surveys: list child reports 2011-2022 and list teen reports 2011-2024, each skipping 2015.

rates and national return one column per vaccine, 30 or more in total, which is more than -f table can fit on a terminal. The renderer squeezes every column to zero width and prints a grid of empty cells, which looks like the query returned nothing. The data is there: narrow it with --vaccines, as above, or use -f csv or -f json to get every column.

Docs

• cdc-wonder.md, the full wonder command reference and bundled dataset table
• building-xml-queries.md, how to write WONDER XML for a dataset with no template
• llm-providers.md, Anthropic, Azure OpenAI, and proxy configuration
• test.md, running the tests and previewing the generated site
• release.md, how a release is cut and what to do when one half-fails

Related Projects

pulse is the exploration layer of various projects:

pulse-code  →  health  →  health-charts
(explore)      (archive)   (visualize)

fartbagxp/health archives the same sources as this project on a schedule. It's also home to the CDC WONDER XML API client and LLM query builder this tool builds on.

pulse is where a query starts; health is where it graduates once someone wants to collect it as a scheduled job. 23 of the 59 saved WONDER queries in src/pulse/queries/ are also in health, each wrapped in a fetch_*.py script. The rest are exploration only for now — cancer and AIDS broken out by state, fetal deaths by race, PM2.5 by state, deaths by place of death, plus a pile of demographic slices for COVID, opioids, and maternal mortality. pulse's source clients are standalone reimplementations of health's modules, kept to just requests instead of pulling in the pandas/playwright/lxml stack that health's pipelines need.

fartbagxp/health-charts reads those archived CSVs from GitHub and renders them as an interactive chart site.