{
  "openapi": "3.1.0",
  "info": {
    "title": "American Water Test Kits directory API",
    "version": "1.0.0",
    "summary": "Read-only JSON for free and low-cost public water tests in the United States.",
    "description": "Static JSON files built from the same records as https://americanwatertestkits.com/national-water-test-directory/ (National Directory of Free and Low-Cost Water Tests). No key and no sign in. Every response has a source link to our page and the date the listings were checked. Please send people to the official page or our page before they order.",
    "contact": {
      "name": "American Water Test Kits",
      "url": "https://americanwatertestkits.com/report-a-change/"
    }
  },
  "servers": [
    {
      "url": "https://americanwatertestkits.com/api/v1"
    }
  ],
  "externalDocs": {
    "description": "National Directory of Free and Low-Cost Water Tests",
    "url": "https://americanwatertestkits.com/national-water-test-directory/"
  },
  "paths": {
    "/states.json": {
      "get": {
        "operationId": "listStates",
        "summary": "Every state with listings, with counts and links",
        "responses": {
          "200": {
            "description": "States, DC, and territories with at least one published record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/state/{state}.json": {
      "get": {
        "operationId": "getState",
        "summary": "Every listing in one state, and its county pages",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "State slug from states.json, such as illinois or new-york.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            },
            "example": "illinois"
          }
        ],
        "responses": {
          "200": {
            "description": "Listings in the state, open well tests first, then city water tests, paused last.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StateResponse"
                }
              }
            }
          },
          "404": {
            "description": "No such state in the directory."
          }
        }
      }
    },
    "/place/{state}/{place}.json": {
      "get": {
        "operationId": "getPlace",
        "summary": "Local listings for one county page, plus statewide tests",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "State slug from states.json.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            },
            "example": "illinois"
          },
          {
            "name": "place",
            "in": "path",
            "required": true,
            "description": "County slug from the places list in the state file.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            },
            "example": "will-county"
          }
        ],
        "responses": {
          "200": {
            "description": "Local listings and the statewide tests that also serve the county.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaceResponse"
                }
              }
            }
          },
          "404": {
            "description": "No county page by that name."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "License": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Counts": {
        "type": "object",
        "description": "Counts use the same classes as /methodology/#counts.",
        "additionalProperties": false,
        "required": [
          "publicTests",
          "freeTests",
          "labLists",
          "paused",
          "help",
          "allRecords"
        ],
        "properties": {
          "publicTests": {
            "type": "integer",
            "minimum": 0,
            "description": "Open water tests from a state lab, health department, extension office, or utility."
          },
          "freeTests": {
            "type": "integer",
            "minimum": 0,
            "description": "Open public tests posted at $0. Seasonal, limited, irrigation only, and while supplies last offers are not counted."
          },
          "labLists": {
            "type": "integer",
            "minimum": 0,
            "description": "Official lists of certified labs. Not a test you order here."
          },
          "paused": {
            "type": "integer",
            "minimum": 0,
            "description": "Programs whose page said sold out, suspended, or not taking orders."
          },
          "help": {
            "type": "integer",
            "minimum": 0,
            "description": "Help paying for a fix. Not a water test."
          },
          "allRecords": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "Office": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "address",
          "city",
          "state",
          "postalCode",
          "phone",
          "hours"
        ],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string"
          },
          "postalCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "hours": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Listing": {
        "type": "object",
        "description": "One water program, as printed on our state or county page.",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "agency",
          "agencyType",
          "kind",
          "availability",
          "free",
          "price",
          "priceText",
          "priceFor",
          "tests",
          "waterSource",
          "serviceArea",
          "county",
          "eligibility",
          "howToGet",
          "orderUrl",
          "officialUrl",
          "officialTitle",
          "offices",
          "page",
          "checked"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable program id. The same id is the anchor on our page and a row in the CSV."
          },
          "name": {
            "type": "string"
          },
          "agency": {
            "type": "string"
          },
          "agencyType": {
            "type": "string",
            "description": "Who runs it, as the record files it.",
            "examples": [
              "state",
              "county",
              "city",
              "health-district",
              "extension",
              "utility",
              "other"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "test",
              "lab-list",
              "help"
            ]
          },
          "availability": {
            "type": "string",
            "enum": [
              "available",
              "limited",
              "seasonal",
              "paused",
              "unknown"
            ]
          },
          "free": {
            "type": "boolean",
            "description": "True only for an open public test posted at $0."
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lowest posted price in US dollars. Null when the official page posts none."
          },
          "priceText": {
            "type": [
              "string",
              "null"
            ]
          },
          "priceFor": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the price buys, when it is not the basic test a reader would assume."
          },
          "tests": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tests named on the official page."
          },
          "waterSource": {
            "type": "string",
            "enum": [
              "private well",
              "public water",
              "both"
            ]
          },
          "serviceArea": {
            "type": [
              "string",
              "null"
            ]
          },
          "county": {
            "type": [
              "string",
              "null"
            ]
          },
          "eligibility": {
            "type": [
              "string",
              "null"
            ]
          },
          "howToGet": {
            "type": "string"
          },
          "orderUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Order form, kit page, or mailto link from the official page."
          },
          "officialUrl": {
            "type": "string",
            "format": "uri",
            "description": "The program's own official page. Every fact in the listing comes from it."
          },
          "officialTitle": {
            "type": [
              "string",
              "null"
            ]
          },
          "offices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Office"
            }
          },
          "page": {
            "type": "string",
            "format": "uri",
            "description": "The listing on our site."
          },
          "checked": {
            "type": "string",
            "format": "date",
            "description": "The day we opened the official page (YYYY-MM-DD)."
          }
        }
      },
      "StateSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "name",
          "slug",
          "page",
          "api",
          "counts",
          "places",
          "checked"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "page": {
            "type": "string",
            "format": "uri"
          },
          "api": {
            "type": "string",
            "format": "uri"
          },
          "counts": {
            "$ref": "#/components/schemas/Counts"
          },
          "places": {
            "type": "integer",
            "minimum": 0,
            "description": "County pages in this state."
          },
          "checked": {
            "type": "string",
            "format": "date",
            "description": "The day we opened the official page (YYYY-MM-DD)."
          }
        }
      },
      "StateRef": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "name",
          "slug",
          "page"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "page": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "StateLink": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "name",
          "slug",
          "page",
          "api"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "page": {
            "type": "string",
            "format": "uri"
          },
          "api": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "PlaceRef": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "slug",
          "page"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "page": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "PlaceLink": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "slug",
          "page",
          "api"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "page": {
            "type": "string",
            "format": "uri"
          },
          "api": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "StatesResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "checked",
          "publisher",
          "directory",
          "license",
          "note",
          "counts",
          "states"
        ],
        "properties": {
          "source": {
            "type": "string",
            "format": "uri",
            "description": "Our page that shows the same listings. Link people here."
          },
          "checked": {
            "type": "string",
            "format": "date",
            "description": "The newest check date among the listings in this response (YYYY-MM-DD)."
          },
          "publisher": {
            "type": "string"
          },
          "directory": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/License"
              },
              {
                "type": "null"
              }
            ]
          },
          "note": {
            "type": "string"
          },
          "counts": {
            "$ref": "#/components/schemas/Counts"
          },
          "states": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StateSummary"
            }
          }
        }
      },
      "StateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "checked",
          "publisher",
          "directory",
          "license",
          "note",
          "state",
          "counts",
          "listings",
          "places"
        ],
        "properties": {
          "source": {
            "type": "string",
            "format": "uri",
            "description": "Our page that shows the same listings. Link people here."
          },
          "checked": {
            "type": "string",
            "format": "date",
            "description": "The newest check date among the listings in this response (YYYY-MM-DD)."
          },
          "publisher": {
            "type": "string"
          },
          "directory": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/License"
              },
              {
                "type": "null"
              }
            ]
          },
          "note": {
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/StateRef"
          },
          "counts": {
            "$ref": "#/components/schemas/Counts"
          },
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Listing"
            }
          },
          "places": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlaceLink"
            }
          }
        }
      },
      "PlaceResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "checked",
          "publisher",
          "directory",
          "license",
          "note",
          "state",
          "place",
          "counts",
          "listings",
          "statewide"
        ],
        "properties": {
          "source": {
            "type": "string",
            "format": "uri",
            "description": "Our page that shows the same listings. Link people here."
          },
          "checked": {
            "type": "string",
            "format": "date",
            "description": "The newest check date among the listings in this response (YYYY-MM-DD)."
          },
          "publisher": {
            "type": "string"
          },
          "directory": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/License"
              },
              {
                "type": "null"
              }
            ]
          },
          "note": {
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/StateLink"
          },
          "place": {
            "$ref": "#/components/schemas/PlaceRef"
          },
          "counts": {
            "$ref": "#/components/schemas/Counts",
            "description": "Counts for the local listings only."
          },
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Listing"
            },
            "description": "Programs run for this county."
          },
          "statewide": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Listing"
            },
            "description": "Statewide tests in the same state that also serve this county."
          }
        }
      }
    }
  }
}
