Skip to content

Data Technical Specifications

Version 2.0.0 (updated 2026-05-18)
  • Updated field-level specifications to cover the expanded supported disease set.
  • Clarified disease-specific valid values for confirmation_status and disease_subtype.
  • Synchronized technical specs with current templates and data standards tooling behavior.

Overview

This document provides the complete technical specifications for disease tracking data submissions to the US Disease Tracker system. These specifications define the required and optional fields, data types, valid values, and formatting requirements for submitting aggregate disease case count data.

Important: This is for aggregate data only. No line-level (individual case) data should be submitted.

Note: For high-level submission guidance including what data to submit, when to submit it, and case classification rules, see the Data Submission Guide.

Contents

Data Structure

Data should be submitted in CSV format with one row per unique combination of:

  • Time period (week)
  • Geographic unit
  • Disease
  • Age group (when applicable)
  • Disease subtype (when applicable)
  • Outcome (cases or deaths)


Case-sensitivity

All field names and values are case-sensitive. Follow the specifications below to ensure correct use of capitalization. In general, capitalization should only be applied to proper nouns, such as for jurisdiction or subjurisdiction names, and disease subtypes (e.g., A, B, C, etc.)


Field Summary

The following table provides a comprehensive overview of all data fields required for submission:

Field Name Data Type Description Valid Values Required
time_unit String Time aggregation unit week Yes
report_period_start Date Start date of reporting period (MMWR week aligned) ISO 8601 format (YYYY-MM-DD) Yes
report_period_end Date End date of reporting period (MMWR week aligned) ISO 8601 format (YYYY-MM-DD) Yes
date_type String Method used to assign cases to reporting periods cccd, jurisdiction date hierarchy Yes
disease_name String Name of disease being reported measles, pertussis, meningococcus, hepatitis a, acute hepatitis b, perinatal hepatitis b, mumps, mpox, varicella, pediatric flu mortality Yes
outcome String Type of outcome being reported cases, deaths Yes
confirmation_status String Case confirmation level confirmed, confirmed and probable Yes
reporting_jurisdiction String Jurisdiction submitting the data Two-letter state/territory code or NYC Yes
state String State/territory containing the geographic unit Two-letter state/territory code Yes
geo_unit String Type of geographic unit county, state, region, planning area, hsa, NA Yes
geo_name String Name of the geographic unit Name string or international resident, unknown, unspecified Yes
count Integer Number of cases for this combination Positive integers Yes
age_group String Age group of cases <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified Yes
disease_subtype String Disease subtype (meningococcal serogroup) A, B, C, W, X, Y, Z, nongroupable, total, unknown, unspecified Yes

Key Notes:

  • Report Period: Use MMWR week boundaries for weekly reporting
  • Disease-Specific Rules: Measles, Hepatitis A, Perinatal Hepatitis B, and Influenza-Associated Pediatric Mortality use confirmed only; Pertussis, Meningococcus, Acute Hepatitis B, Mumps, Mpox, and Varicella use confirmed and probable
  • Geographic Units: Use standard two-letter abbreviations (AL, AK, ..., WY, DC, PR, etc.); for international residents use geo_name = "international resident" and geo_unit = "NA"; for suppressed small counts use geo_name = "unspecified"
  • Age Groups: Age groups are submitted at jurisdiction level only (not sub-jurisdiction); use age_group = "total" for non-age stratifications.
  • Perinatal Hepatitis B exception: Age group stratifications are not collected for Perinatal Hepatitis B; report only age_group = "total"
  • Disease Subtype: Use disease_subtype = "total" for non-subtype stratifications or diseases without subtype reporting; use disease_subtype = "unknown" when subtyping was not performed; use disease_subtype = "nonsubtypeable" when subtyping was performed but specimens could not be subtyped, and use disease_subtype = "unspecified" when subtype is known but suppressed
  • Counts: Only include non-zero counts; apply jurisdiction data suppression policies before submission
  • Capitalization: All fields are case-sensitive. Follow the specifics defined here for correct value options.


No Zero Reporting

Only include rows with non-zero counts. The system will automatically infer zeros for missing combinations at higher aggregation levels.

Fields Specifications


Reporting Period Fields

Field Name Data Type Description Valid Values
time_unit String Time aggregation unit week
report_period_start Date Start date of reporting period (MMWR-aligned) ISO 8601 format (YYYY-MM-DD)
report_period_end Date End date of reporting period (MMWR-aligned) ISO 8601 format (YYYY-MM-DD)
date_type String Method used to assign cases to reporting time periods cccd, jurisdiction date hierarchy

Notes:

  • Use MMWR week boundaries for weekly reporting
  • Provide metadata describing custom date hierarchies if not using CCCD


Disease Fields

Field Name Data Type Description Valid Values
disease_name String Name of disease being reported measles, pertussis, meningococcus, hepatitis a, acute hepatitis b, perinatal hepatitis b, mumps, mpox, varicella, pediatric flu mortality
outcome String Type of outcome being reported cases, deaths
confirmation_status String Case confirmation level confirmed, confirmed and probable

Notes:

  • Measles, Hepatitis A, Perinatal Hepatitis B, and Influenza-Associated Pediatric Mortality: Use confirmed only
  • Pertussis, Meningococcus, Acute Hepatitis B, Mumps, Mpox, and Varicella: Use confirmed and probable
  • Additional outcomes (hospitalizations) planned for future


Geographic Fields

Field Name Data Type Description Valid Values
reporting_jurisdiction String Jurisdiction submitting the data Two-letter state/territory code or NYC
state String State/territory containing the geographic unit Two-letter state/territory code
geo_unit String Type of geographic unit county, state, region, planning area, hsa, NA
geo_name String Name of the geographic unit Name string or unspecified, unknown, international resident

Notes:

  • Use standard two-letter abbreviations (AL, AK, ..., WY, DC, PR, etc.)
  • For international residents: use geo_name = "international resident" and geo_unit = "NA"
  • Metadata should include all geographic unit names used
  • Disease subtype is currently collected at jurisdiction level only (not sub-jurisdiction)
  • Currently only use for meningococcal disease serogroup reporting
  • Use total for non-subtype-stratified aggregations
  • Use total for diseases without subtype reporting (measles, pertussis, hepatitis a, acute hepatitis b, perinatal hepatitis b, mumps, mpox, varicella, pediatric flu mortality)
  • Use unknown when subtyping was not performed or is otherwise not known (only for disease_subtype aggregations)
  • Use unspecified when geo_name is known but suppressed in subjurisdiction aggregations


Count Field

Field Name Data Type Description Valid Values
count Integer Number of cases for this combination Positive integers

Notes:

  • Only include non-zero counts
  • Apply jurisdiction data suppression policies before submission
  • Use geo_name = "unspecified" for suppressed counts to maintain totals


Demographic Fields

Field Name Data Type Description Valid Values
age_group String Age group of cases See age group table below

Valid Age Groups

Value Description
<1 y From birth up to but not including 1 year birthday
1-4 y From 1 year birthday up to but not including 5 year birthday
5-11 y From 5 year birthday up to but not including 12 year birthday
12-18 y From 12 year birthday up to but not including 19 year birthday
19-22 y From 19 year birthday up to but not including 23 year birthday
23-44 y From 23 year birthday up to but not including 45 year birthday
45-64 y From 45 year birthday up to but not including 65 year birthday
>=65 y From 65 year birthday and older
total All ages combined
unknown Age unknown
unspecified Age known but suppressed

Notes:

  • Age group is currently accepted at jurisdiction level only (not sub-jurisdiction)
  • Same age groupings used for all diseases
  • Use total for non-age-stratified aggregations
  • Use unknown when age information is truely unknown (only for age_group aggregations)
  • Use unspecified when age group is known but suppressed


Valid Age Groups by Condition

Disease Valid Age Groups Notes
measles <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified
pertussis <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified
meningococcus <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified
hepatitis a <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified
acute hepatitis b <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified
perinatal hepatitis b total only <2yrs
mumps <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified
mpox <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified
varicella <1 y, 1-4 y, 5-11 y, 12-18 y, 19-22 y, 23-44 y, 45-64 y, >=65 y, total, unknown, unspecified
pediatric flu mortality <1 y, 1-4 y, 5-11 y, 12-18 y, total, unknown, unspecified


Disease-Specific Fields

Field Name Data Type Description Valid Values
disease_subtype String Disease subtype (meningococcal serogroup) A, B, C, W, X, Y, Z, total, unknown, unspecified,nonsubtypeable

Notes:

  • Disease subtype is currently accepted at jurisdiction level only (not sub-jurisdiction)
  • Currently only use for meningococcal disease serogroup reporting
  • Use total for non-subtype-stratified aggregations
  • Use total for diseases without subtype reporting (measles, pertussis, hepatitis a, acute hepatitis b, perinatal hepatitis b, mumps, mpox, varicella, pediatric flu mortality)
  • Use unknown when subtyping was not performed or is otherwise not known (only for disease_subtype aggregations)
  • Use unspecified when subtype is known but suppressed


Valid Subtypes by Condition

Disease Valid Subtypes
measles total
pertussis total
meningococcus A, B, C, W, X, Y, Z, total, unknown, unspecified,nonsubtypeable
hepatitis a total
acute hepatitis b total
perinatal hepatitis b total
mumps total
mpox total
varicella total
pediatric flu mortality total



Validation

See Validation for details on file and data validation.



Example Data

Example data files are available to help understand the required format:

File naming convention:

Files should be named following the pattern:

disease_tracking_report_{jurisdiction}_{report_date}.csv

Examples:

  • disease_tracking_report_CA-SIMULATED-EXAMPLE_2026-02-09.csv (California state, submitted February 9, 2026. These are partially simulated data and should not be assumed to be real data.)



Metadata Requirements

Jurisdictions should provide accompanying metadata using the Jurisdiction Reporting Metadata Template. Metadata required includes:

  1. Date Classification Method a. If using CCCD, indicate "cccd" b. If using custom hierarchy, provide detailed description

  2. Geographic Units a. List of all geographic unit names used b. Mapping of units to parent jurisdictions (if applicable)

  3. Data Suppression Policies a. Rules for small count suppression b. How suppressed counts are aggregated

  4. Contact Information a. Technical point of contact b. Data quality contact



Version History

Version Date Changes
2.0.0 2026-05-18 Expanded supported diseases and updated documentation/tool guidance for disease-specific value rules
1.1.0 2026-02-09 Updated standards. Moves to weekly only, clarifies value use-cases, removes ytd, clarifies data sub-aggregations
1.0.0 2026-01-06 Initial draft for pilot phase



References

Questions

For questions about these technical specifications, see the Data Submission Guide or contact the project team.