API Documentation

The Cleartap API is a RESTful API that allows you to access to all water systems and their contaminant data.

Authentication

All API requests require a Bearer token in the Authorization header. You can get your API token by contacting us here.

Example Request

curl -X GET https://www.cleartap.com/api/v1/search?zipcode=12345 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Search Water Systems

Returns a list of water systems that match the zipcode (usually want the first result) and all of their contaminant data.

GET /v1/search?zipcode=

curl -X GET https://www.cleartap.com/api/v1/search?zipcode=12345 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Format

reportURL only returns a PDF for the top 25 (by population served) water systems, for verification purposes.

{
  "waterSystems": [
    {
      "name": "Example Water System",
      "reportUrl": "https://www.cleartap.com/api/v1/ccrs/12345",
      "pwsId": "XX0000001",
      "pwsType": "CWS",
      "waterSource": "SW",
      "serviceConnections": 100000,
      "populationServed": 500000,
      "state": "XX",
      "serviceAreas": {
        "zips": ["12345", "12346", "12347"],
        "cities": ["Example City"],
        "counties": ["Example County"]
      },
      "contaminants": {
        "detected": [
          {
            "name": "Example Contaminant",
            "category": "Example Category",
            "level": "0.500",
            "units": "ppb",
            "limit": "10.000",
            "limitSource": "EPA",
            "aliases": ["alternative_name"],
            "healthEffects": "Description of potential health effects",
            "summary": "Brief overview of the contaminant",
            "details": "Detailed information about the contaminant",
            "year": 2023,
            "sites": [],
            "source": "ccr"
          }
        ],
        "exceeded": [],
        "tested": [
          {
            "name": "Example Tested Contaminant",
            "category": "Example Category",
            "level": "ND",
            "units": "ppb",
            "aliases": [],
            "healthEffects": null,
            "summary": "Brief overview of tested contaminant",
            "details": "Detailed information about tested contaminant",
            "year": 2023,
            "sites": [],
            "source": "ccr"
          }
        ]
      }
    }
  ]
}

Rate Limits

API requests are limited to 1000 requests per minute per API token.