{"openapi": "3.1.0", "info": {"title": "MeaslesWatch - free local API", "version": "1.2.0", "description": "No login or fees. Only validated manually ingested snapshots are served; see /sources for actual coverage. CDC exact values cover 52 reporting jurisdictions, with NYC separate. Available independent state adapters and their dates are listed in /sources; an excluded source is not silently replaced with CDC. Utah publishes diagnosed resident cases, without a separately specified confirmation status. Dates are source report dates; fetched_at is retrieval time. stale is separate from status. last_known_good retains evidence during failures. view=latest selects each validated state adapter; never merged into CDC totals. News uses a seven-day index/publication window; category=US is the default, context includes world/general/uncertain records, and all returns both. State geo filters exclude uncertain geography. A result cap or source failure appears in warning. Anonymous global pool defaults to 240 requests/minute. Responses cached internally for 30 seconds; all API responses, including rejected and cached requests, are metered. Unknown parameters are rejected. No ingestion/admin HTTP endpoint."}, "servers": [{"url": "/"}], "paths": {"/api/v1/summary": {"get": {"summary": "CDC national measures in a single snapshot; null until validated", "parameters": [{"name": "year", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 2000, "maximum": 2026}}], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/states": {"get": {"summary": "All states/DC plus separate NYC. Never infer missing counts.", "parameters": [{"name": "view", "in": "query", "required": false, "schema": {"type": "string", "enum": ["cdc", "latest"], "default": "cdc"}}, {"name": "year", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 2000, "maximum": 2026}}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 100, "description": "State name or abbreviation"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "maximum": 10000}}], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Page"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/states/{id}": {"get": {"summary": "One jurisdiction and available Texas residence-county records", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "view", "in": "query", "required": false, "schema": {"type": "string", "enum": ["cdc", "latest"], "default": "cdc"}}, {"name": "year", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 2000, "maximum": 2026}}], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/State"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/sources": {"get": {"summary": "Source health, attribution, last check versus data date, and planned integrations", "parameters": [], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/news": {"get": {"summary": "Metadata only; indexed time is not publication time; incomplete discovery coverage", "parameters": [{"name": "geo", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "category", "in": "query", "required": false, "schema": {"type": "string", "enum": ["US", "context", "all"], "default": "US"}}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 100, "description": "Case-insensitive headline or publisher substring; composed with geography/category before pagination"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "maximum": 10000}}], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/NewsPage"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/usage": {"get": {"summary": "Local aggregate metering; no IP history, authentication, identity or billing", "parameters": [], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/example": {"get": {"summary": "Verified source excerpt paired with exact summary record; labeled research-only example when no accepted record exists", "parameters": [], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/openapi.json": {"get": {"summary": "This API contract", "parameters": [], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/county-layer": {"get": {"summary": "Independent latest county reports for the year, with exact Census national coordinates and separate source/date provenance", "parameters": [{"name": "year", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 2000, "maximum": 2026}}], "responses": {"200": {"description": "JSON response; absent observations are null, not zero", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CountyLayer"}}}}, "400": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Standard error; 429 includes Retry-After", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}}, "components": {"schemas": {"Observation": {"type": "object", "required": ["source_id", "canonical_url", "geo_id", "scope", "measure", "value", "status", "period_start", "period_end", "data_as_of", "source_published_at", "fetched_at", "parser_version", "sha256", "revision", "snapshot_id"], "properties": {"source_id": {"type": "string"}, "canonical_url": {"type": "string"}, "geo_id": {"type": "string"}, "scope": {"type": "string"}, "measure": {"type": "string"}, "definition": {"type": "string"}, "period_start": {"type": "string"}, "period_end": {"type": "string"}, "data_as_of": {"type": "string"}, "fetched_at": {"type": "string"}, "parser_version": {"type": "string"}, "sha256": {"type": "string"}, "outbreak_status": {"type": "string"}, "source_excerpt": {"type": "string"}, "value": {"type": ["integer", "null"], "minimum": 0}, "status": {"enum": ["reported", "suppressed", "unreported", "unavailable"]}, "source_published_at": {"type": ["string", "null"]}, "source_updated_at": {"type": ["string", "null"]}, "revision": {"type": "integer"}, "snapshot_id": {"type": "integer"}, "period_basis": {"type": "string", "description": "CDC surveillance-year scope; calendar labels do not assert individual onset dates"}, "supporting_sources": {"type": "array", "items": {"type": "object", "required": ["url", "sha256"], "properties": {"url": {"type": "string"}, "sha256": {"type": "string"}}}}}}, "State": {"type": "object", "required": ["id", "name", "value", "status", "observation", "data_as_of", "stale", "source_status"], "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "value": {"type": ["integer", "null"]}, "status": {"enum": ["reported", "suppressed", "unreported", "unavailable"]}, "observation": {"anyOf": [{"$ref": "#/components/schemas/Observation"}, {"type": "null"}]}, "data_as_of": {"type": ["string", "null"]}, "stale": {"type": ["boolean", "null"]}, "source_status": {"type": "string"}, "warning": {"type": ["string", "null"]}, "source_id": {"type": ["string", "null"]}, "view": {"enum": ["cdc", "latest"]}, "year": {"type": "integer"}, "counties": {"type": "array", "items": {"$ref": "#/components/schemas/Observation"}}, "county_detail": {"$ref": "#/components/schemas/CountyDetail"}}}, "Error": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}, "Page": {"type": "object", "required": ["items", "total", "limit", "offset", "next_offset"], "properties": {"items": {"type": "array", "items": {"type": "object"}}, "total": {"type": "integer"}, "limit": {"type": "integer"}, "offset": {"type": "integer"}, "next_offset": {"type": ["integer", "null"]}}}, "CountyDetail": {"type": "object", "required": ["available", "reason", "items"], "description": "Texas latest-state residence breakdown only when one validated source/year/period matches. Geometry is Census 2024, separate from case provenance. Unlisted reference counties are absent, never zero. Unmatched source rows remain flagged without symbols.", "properties": {"available": {"type": "boolean"}, "reason": {"type": ["string", "null"]}, "title": {"type": "string"}, "geometry": {"type": "object", "description": "Versioned Census reference URL, hash, retrieval date, interior-point fields, FIPS join and separate boundary provenance."}, "scale": {"type": "object", "description": "r = 2.4 * sqrt(positive reported count), in 600 x 520 SVG units. Map and legend scale together; no visual radius clamps."}, "coverage": {"type": "object", "description": "Source/mapped/unmapped record counts, reference/absent county counts and positive symbol count."}, "items": {"type": "array", "items": {"type": "object", "required": ["id", "name", "geoid", "mapped", "mapping_status", "value", "status", "radius", "observation"], "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "geoid": {"type": ["string", "null"]}, "mapped": {"type": "boolean"}, "mapping_status": {"enum": ["matched", "unmapped_name", "reference_only"]}, "value": {"type": ["integer", "null"]}, "status": {"type": "string"}, "radius": {"type": "number", "minimum": 0}, "x": {"type": ["number", "null"]}, "y": {"type": ["number", "null"]}, "observation": {"anyOf": [{"$ref": "#/components/schemas/Observation"}, {"type": "null"}]}}}}}}, "News": {"type": "object", "required": ["url", "title", "publisher", "kind", "geo_id", "geography", "published_at", "indexed_at", "first_seen"], "properties": {"url": {"type": "string"}, "title": {"type": "string"}, "publisher": {"type": "string"}, "kind": {"type": "string"}, "geo_id": {"type": "string"}, "classification_reason": {"type": "string"}, "indexed_at": {"type": "string"}, "first_seen": {"type": "string"}, "published_at": {"type": ["string", "null"]}, "updated_at": {"type": ["string", "null"]}, "geography": {"enum": ["US", "world", "general", "uncertain"]}}}, "NewsPage": {"type": "object", "required": ["items", "total", "limit", "offset", "next_offset"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/News"}}, "total": {"type": "integer"}, "limit": {"type": "integer"}, "offset": {"type": "integer"}, "next_offset": {"type": ["integer", "null"]}, "window_days": {"const": 7}, "warning": {"type": ["string", "null"]}, "date_note": {"type": "string"}}}, "CountyLayer": {"type": "object", "required": ["id", "year", "available", "reports", "covered_states", "status", "projection"], "description": "Explicit Latest county reports overlay, independent of CDC/state-fill view. Reuses validated Texas residence observations and versioned Census points. Pure CDC state endpoints still have no county_detail. No visitor-triggered upstream fetch.", "properties": {"id": {"const": "latest_county_reports"}, "year": {"type": "integer"}, "available": {"type": "boolean"}, "status": {"enum": ["reported", "unavailable"]}, "warning": {"type": ["string", "null"]}, "display_rule": {"type": "object", "description": "Common CSS-pixel radius k*sqrt(count): national k 1.2, national map width below 600px k 0.9, all focused states k 2; same k for legend. Legacy M2 radius/scale fields are unchanged."}, "covered_states": {"type": "array", "items": {"type": "object"}}, "projection": {"type": "object", "description": "national-svg-v1: map_x/map_y match the pinned national state geometry; includes boundary hash and transform."}, "reports": {"type": "array", "items": {"type": "object", "required": ["state_id", "source_id", "observation", "county_detail"], "properties": {"state_id": {"type": "string"}, "source_id": {"type": "string"}, "observation": {"$ref": "#/components/schemas/Observation"}, "county_detail": {"$ref": "#/components/schemas/CountyDetail"}}}}}}}}}