{
  "name": "us-drug-overdose-deaths",
  "title": "US Drug Overdose Deaths (CDC provisional, monthly)",
  "description": "Provisional counts of drug overdose deaths in the United States, for the US as a whole and each state (plus Washington DC, New York City and Puerto Rico), from CDC's National Center for Health Statistics (NCHS). Each value is the number of deaths in the 12 months ending in the given month, from 12 months to January 2015 onward. For each jurisdiction and month there are counts of all overdose deaths and of deaths involving the main drug classes (synthetic opioids such as fentanyl, psychostimulants such as methamphetamine, cocaine, heroin, prescription-type opioids, methadone), both as reported and as predicted by NCHS after adjusting for delayed reporting. Recent months are provisional and will rise as records arrive. Updated monthly.",
  "status": "monitored",
  "version": "1.0.0",
  "keywords": ["overdose", "drug overdose deaths", "opioids", "fentanyl", "public health", "mortality", "united states", "cdc", "nchs"],
  "licenses": [
    {
      "name": "US-PD",
      "title": "Public Domain U.S. Government (as stated in the licence field of the data.cdc.gov dataset page). Data from the CDC National Center for Health Statistics, a US federal agency.",
      "path": "https://www.usa.gov/government-works"
    }
  ],
  "sources": [
    {
      "title": "CDC NCHS - VSRR Provisional Drug Overdose Death Counts (data.cdc.gov dataset xkb8-kh2a)",
      "path": "https://data.cdc.gov/d/xkb8-kh2a"
    },
    {
      "title": "CDC NCHS - Provisional Drug Overdose Death Counts (programme page and technical notes)",
      "path": "https://www.cdc.gov/nchs/nvss/vsrr/drug-overdose-data.htm"
    }
  ],
  "upkeep": {
    "mode": "living",
    "refresh": "monthly",
    "workflow": ".github/workflows/update.yml"
  },
  "resources": [
    {
      "path": "data/overdose-deaths.csv",
      "name": "overdose-deaths",
      "title": "Overdose deaths in the 12 months ending each month, by jurisdiction and drug class",
      "mediatype": "text/csv",
      "encoding": "utf-8",
      "schema": {
        "fields": [
          {"name": "date", "type": "date", "description": "Last day of the month that ends the 12-month period. 2026-06-30 means deaths from 1 July 2025 to 30 June 2026."},
          {"name": "jurisdiction", "type": "string", "description": "Two-letter code: US (the 50 states and DC; excludes Puerto Rico), a state, DC, YC (New York City) or PR (Puerto Rico). NY excludes New York City."},
          {"name": "jurisdiction_name", "type": "string", "description": "Name of the jurisdiction."},
          {"name": "indicator", "type": "string", "description": "What is counted: all_drugs (all drug overdose deaths), opioids (any opioid, T40.0-T40.4, T40.6), synthetic_opioids (synthetic opioids other than methadone, mainly fentanyl, T40.4), psychostimulants (psychostimulants with abuse potential, mainly methamphetamine, T43.6), cocaine (T40.5), heroin (T40.1), natural_semisynthetic_opioids (natural and semi-synthetic opioids such as oxycodone, T40.2), methadone (T40.3). A death can involve several drugs, so drug classes overlap and do not sum to all_drugs.", "constraints": {"enum": ["all_drugs", "opioids", "synthetic_opioids", "psychostimulants", "cocaine", "heroin", "natural_semisynthetic_opioids", "methadone"]}},
          {"name": "reported_deaths", "type": "integer", "description": "Reported provisional count of deaths. Empty when CDC suppresses it (fewer than 10 deaths) or does not show it (low data quality)."},
          {"name": "predicted_deaths", "type": "integer", "description": "NCHS predicted count, adjusted for delayed reporting. Never below the reported count in this data; empty where CDC does not publish one."},
          {"name": "note", "type": "string", "description": "suppressed (fewer than 10 deaths), low_quality (not shown by CDC due to low data quality), or empty.", "constraints": {"enum": ["", "suppressed", "low_quality"]}},
          {"name": "incomplete", "type": "boolean", "description": "true where CDC flags the count as underreported due to incomplete data (the most recent months)."}
        ],
        "primaryKey": ["jurisdiction", "date", "indicator"]
      }
    },
    {
      "path": "data/reporting-quality.csv",
      "name": "reporting-quality",
      "title": "Reporting completeness by jurisdiction and month",
      "mediatype": "text/csv",
      "encoding": "utf-8",
      "schema": {
        "fields": [
          {"name": "date", "type": "date", "description": "Last day of the month that ends the 12-month period."},
          {"name": "jurisdiction", "type": "string", "description": "Two-letter jurisdiction code, as in overdose-deaths."},
          {"name": "jurisdiction_name", "type": "string", "description": "Name of the jurisdiction."},
          {"name": "all_cause_deaths", "type": "integer", "description": "Provisional count of deaths from all causes in the 12-month period."},
          {"name": "percent_complete", "type": "number", "description": "Percentage of expected death records received (CDC's completeness measure for the period)."},
          {"name": "percent_pending_investigation", "type": "number", "description": "Percentage of death records whose cause is still pending investigation."},
          {"name": "percent_with_drugs_specified", "type": "number", "description": "Percentage of drug overdose deaths with at least one specific drug named on the death certificate. Low values make drug-class counts less reliable."}
        ],
        "primaryKey": ["jurisdiction", "date"]
      }
    }
  ],
  "views": [
    {
      "name": "us-overdose-deaths",
      "title": "US drug overdose deaths in the 12 months ending each month (reported and predicted)",
      "resources": ["overdose-deaths"],
      "specType": "vega-lite",
      "spec": {
        "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
        "width": "container",
        "height": 320,
        "transform": [
          {"filter": "datum.jurisdiction === 'US' && datum.indicator === 'all_drugs'"},
          {"calculate": "toNumber(datum.reported_deaths)", "as": "Reported"},
          {"calculate": "toNumber(datum.predicted_deaths)", "as": "Predicted"},
          {"fold": ["Reported", "Predicted"], "as": ["series", "deaths"]}
        ],
        "mark": {"type": "line"},
        "encoding": {
          "x": {"field": "date", "type": "temporal", "title": "12 months ending"},
          "y": {"field": "deaths", "type": "quantitative", "title": "Deaths"},
          "color": {"field": "series", "type": "nominal", "title": null}
        }
      }
    }
  ]
}
