Skip to content

Data Technical Specifications

Version 1.1.0 (updated 2026-02-09)
  • Updated version of documentation to clarify new standards
  • Serogrouping for meningococcus: Report only at the state/reporting jurisdiction level as reporting at smaller geographies would likely lead to data suppression; report separately from age.
  • Age Groups: Reported at the state/reporting jurisdiction level; Combined the <1 year age groups (currently 0-6 months and 6-12 months) for current diseases (measles, pertussis, meningococcus) into a single “<1 year” category.
  • Removed “YTD” value as a valid option for time_unit.
  • Removed monthly aggregations; only weekly aggregation of cases by MMWR week for all diseases.
  • New value uses implemented: total, unknown, unspecified have specified meaning and uses, NA is only valid if geo_name = "international resident".

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 (currently only cases)


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 Yes
outcome String Type of outcome being reported cases, hospitalizations, 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, total, unknown, unspecified Yes

Key Notes:

  • Report Period: Use MMWR week boundaries for weekly reporting
  • Disease-Specific Rules: Measles uses confirmed only; Pertussis and Meningococcus 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 displayed at jurisdiction level only (not sub-jurisdiction); use total for non-age-stratified aggregations
  • Disease Subtype: Use total for non-subtype-stratified aggregations or diseases without subtype reporting (measles, pertussis); use unknown when subtyping was not performed; use unspecified when subtype is known but suppressed
  • Counts: Only include non-zero counts; apply jurisdiction data suppression policies before submission


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
outcome String Type of outcome being reported cases, hospitalizations, deaths
confirmation_status String Case confirmation level confirmed, confirmed and probable

Notes:

  • Measles: Use confirmed only
  • Pertussis and Meningococcus: Use confirmed and probable
  • Additional outcomes (hospitalizations, deaths) 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 diseases without subtype reporting (measles, pertussis)
  • 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


Disease-Specific Fields

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

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 diseases without subtype reporting (measles, pertussis)
  • 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



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
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.