{
  "openapi": "3.1.0",
  "info": {
    "title": "The Water Map API",
    "version": "1.0.0",
    "summary": "Free, no-key JSON API for verified U.S. drinking-water quality data.",
    "description": "Every U.S. public water utility is required to publish an annual Consumer Confidence Report (CCR) listing the contaminants in its tap water. The Water Map transcribes those reports into a structured dataset and exposes it as a public JSON API. No API key, no rate limit, CC BY 4.0. Source documents linked per system.\n\nTwo endpoints:\n- `GET /api/water` — list every verified system with rolled-up status\n- `GET /api/water/{state}/{city}/{year}` — one system's full structured contaminant facts\n\nThe per-system endpoint mirrors what's rendered at `/water/{state}/{city}/{year}` on the website. The Markdown twin of the same data is at `/water/{state}/{city}/{year}/llms.txt` (declared via `<link rel=\"alternate\" type=\"text/markdown\">`). A site-wide Markdown index per the llms.txt convention is at `/llms.txt`.",
    "termsOfService": "https://www.thewatermap.com/license",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "The Water Map",
      "url": "https://www.thewatermap.com",
      "email": "licensing@thewatertest.com"
    }
  },
  "servers": [
    { "url": "https://www.thewatermap.com", "description": "Production" }
  ],
  "externalDocs": {
    "description": "API + MCP documentation",
    "url": "https://www.thewatermap.com/api-access"
  },
  "tags": [
    { "name": "water-systems", "description": "Public drinking-water utility data, sourced from each utility's annual Consumer Confidence Report." }
  ],
  "paths": {
    "/api/water": {
      "get": {
        "operationId": "listWaterSystems",
        "summary": "List every verified U.S. public water system",
        "description": "Returns the rolled-up status of every system in the dataset. One entry per (utility × year). Use this to discover systems, then call `/api/water/{state}/{city}/{year}` for full structured contaminant facts.",
        "tags": ["water-systems"],
        "responses": {
          "200": {
            "description": "Index of verified water systems.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SystemIndex" }
              }
            }
          },
          "503": {
            "description": "Dataset temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/water/{state}/{city}/{year}": {
      "get": {
        "operationId": "getWaterSystem",
        "summary": "Get one water system's full contaminant facts",
        "description": "Returns the full structured contaminant measurements for one public water system in one reporting year. Mirrors the HTML page at `/water/{state}/{city}/{year}` and the Markdown twin at `/water/{state}/{city}/{year}/llms.txt`.",
        "tags": ["water-systems"],
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "Two-letter U.S. state code, lowercase (e.g. `tx`, `ca`).",
            "schema": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[a-z]{2}$" },
            "example": "ca"
          },
          {
            "name": "city",
            "in": "path",
            "required": true,
            "description": "Kebab-case city slug (e.g. `houston`, `los-angeles`, `chula-vista-otay`).",
            "schema": { "type": "string" },
            "example": "santa-clarita"
          },
          {
            "name": "year",
            "in": "path",
            "required": true,
            "description": "Reporting year of the Consumer Confidence Report.",
            "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 },
            "example": 2024
          }
        ],
        "responses": {
          "200": {
            "description": "Full structured facts for one system.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SystemDetail" }
              }
            }
          },
          "404": {
            "description": "No system at that path.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "503": {
            "description": "Dataset temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SystemIndex": {
        "type": "object",
        "properties": {
          "dataset": { "$ref": "#/components/schemas/DatasetMeta" },
          "meta": {
            "type": "object",
            "properties": {
              "systemCount": { "type": "integer" },
              "contaminantMeasurementsTotal": { "type": "integer" },
              "generatedAt": { "type": "string", "format": "date-time" }
            }
          },
          "endpoints": {
            "type": "object",
            "properties": {
              "listSystems": { "type": "string", "format": "uri" },
              "getSystem": { "type": "string", "description": "URL template — substitute {state}/{city}/{year}." }
            }
          },
          "systems": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/SystemSummary" }
          }
        }
      },
      "SystemSummary": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "City/utility display name.", "example": "Santa Clarita" },
          "state": { "type": "string", "description": "Two-letter U.S. state code (lowercase).", "example": "ca" },
          "year": { "type": "integer", "example": 2024 },
          "page": { "type": "string", "format": "uri", "description": "Canonical HTML page URL." },
          "api": { "type": "string", "format": "uri", "description": "Per-system JSON endpoint." },
          "markdown": { "type": "string", "format": "uri", "description": "Per-system Markdown twin." },
          "contaminantsMeasured": { "type": "integer" },
          "contaminantsOverLimit": { "type": "integer", "description": "Count at or above the federal limit, using the regulated statistic (RAA / p90 / average), not max-single spikes." },
          "contaminantsApproaching": { "type": "integer", "description": "Count between 80% and 100% of the federal limit." },
          "lat": { "type": "number" },
          "lng": { "type": "number" }
        }
      },
      "SystemDetail": {
        "type": "object",
        "properties": {
          "dataset": { "$ref": "#/components/schemas/DatasetMeta" },
          "system": { "$ref": "#/components/schemas/SystemSummary" },
          "contaminants": {
            "type": "array",
            "description": "One entry per measured contaminant, with every reported fact row.",
            "items": { "$ref": "#/components/schemas/Contaminant" }
          }
        }
      },
      "Contaminant": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Canonical analyte identifier (e.g. `lead`, `tthm`, `pfoa`).", "example": "lead" },
          "label": { "type": "string", "example": "Lead" },
          "family": { "type": "string", "description": "Contaminant family (e.g. `metals`, `disinfection_byproducts`, `pfas`).", "example": "metals" },
          "status": {
            "type": "string",
            "enum": ["over", "approaching", "under", "none", "detected", "unmeasured"],
            "description": "`over` = compliance statistic ≥ federal limit. `approaching` = ≥ 80% of limit. `under` = below. `detected` = measured but no federal limit. `none` = not detected."
          },
          "ratio": { "type": ["number", "null"], "description": "Ratio of the worst compliance value to the federal limit (e.g. 1.4 = 40% over)." },
          "facts": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Fact" }
          }
        }
      },
      "Fact": {
        "type": "object",
        "description": "One measured row from the utility's CCR.",
        "properties": {
          "valueKind": { "type": "string", "enum": ["single", "range", "non_detect"] },
          "value": { "type": ["number", "string"], "description": "Measured value, or 'Not detected'." },
          "valueLow": { "type": ["number", "null"] },
          "valueHigh": { "type": ["number", "null"] },
          "units": { "type": ["string", "null"], "example": "ppb" },
          "statisticType": {
            "type": "string",
            "description": "How the value was statistically computed (RAA, p90, single sample, max, etc.). Compliance statistics are RAA, p90, and average."
          },
          "samplingContext": { "type": "string", "description": "Where in the system the sample was taken (at_the_tap, distribution_system, source_water, etc.)." },
          "standardValue": { "type": ["number", "null"], "description": "Federal limit for this contaminant." },
          "standardType": { "type": "string", "enum": ["mcl", "mclg", "action_level", "smcl", "mrdl", "treatment_technique", "health_advisory", "none"] }
        }
      },
      "DatasetMeta": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "U.S. Drinking Water Quality — Contaminant Measurements" },
          "description": { "type": "string" },
          "license": { "type": "string", "format": "uri", "example": "https://creativecommons.org/licenses/by/4.0/" },
          "homepage": { "type": "string", "format": "uri" },
          "documentation": { "type": "string", "format": "uri" },
          "markdownIndex": { "type": "string", "format": "uri" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string", "example": "not_found" },
          "message": { "type": "string" }
        }
      }
    }
  }
}