API Documentation

Base URL: https://api.zipcheckup.com/v1

Authentication

All requests require an API key passed in the X-API-Key header.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.zipcheckup.com/v1/zip/90210

Get a free API key at /api/pricing/. No credit card required.

Rate Limiting

Free tier: 100 requests per day per IP address. The daily limit resets at midnight UTC.

Plan	Daily Limit
Free	100 requests/day
Pro ($49/mo)	10,000 requests/day
Enterprise	Custom

Rate limit headers are included in every API response:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per day (e.g., `100`)
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets (midnight UTC)

Example headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711929600

When you exceed the limit, you'll receive a 429 Too Many Requests response with an upgrade URL:

{
  "error": { "message": "Rate limit exceeded. Max 100 requests/day.", "status": 429 },
  "limit": 100,
  "reset": "2026-03-26T00:00:00.000Z",
  "upgrade": "https://zipcheckup.com/api/pricing/"
}

Need more than 100 requests/day? Request higher limits.

Endpoints

Get Water Quality Data by ZIP

GET /v1/zip/{zip}

Returns full water quality data for a U.S. ZIP code, including safety score, contaminants, violations, and water systems.

Parameter	Type	Description
`zip`	string	5-digit U.S. ZIP code (path parameter)

Example response:

{
  "zip": "90210",
  "score": 72,
  "grade": "C",
  "riskLevel": "moderate",
  "dataDate": "2026-03-19",
  "contaminants": [
    {
      "code": "1005",
      "name": "Barium",
      "measured": 0.015,
      "unit": "mg/L",
      "mcl": 2.0,
      "ratio": 0.0075,
      "healthEffects": "Cardiovascular effects"
    }
  ],
  "violations": [...],
  "waterSystems": [...]
}

Get Safety Score Only

GET /v1/zip/{zip}/score

Returns only the safety score, grade, and risk level. Lighter response for dashboards and widgets.

Example response:

{
  "zip": "90210",
  "score": 72,
  "grade": "C",
  "riskLevel": "moderate",
  "dataDate": "2026-03-19"
}

Get State Summary

GET /v1/state/{state}

Returns a summary for a U.S. state: average score, number of ZIPs, top violations, and worst-scoring ZIPs.

Parameter	Type	Description
`state`	string	2-letter state abbreviation (e.g., `CA`, `NY`, `TX`)

Example response:

{
  "state": "CA",
  "name": "California",
  "avgScore": 68,
  "zipCount": 1769,
  "topViolations": [...],
  "worstZips": [...]
}

Get National Rankings

GET /v1/rankings

Returns a ranked list of ZIP codes by water quality score.

Parameter	Type	Default	Description
`limit`	integer	50	Number of results (max 500)
`order`	string	`desc`	`desc` = best first, `asc` = worst first
`state`	string	all	Filter by 2-letter state code

Get Contaminant Reference

GET /v1/contaminant/{code}

Returns reference information about a contaminant: name, EPA MCL, health effects, and common sources.

Parameter	Type	Description
`code`	string	Contaminant code (from ZIP endpoint response)

Bulk ZIP Lookup Pro+

POST /v1/bulk/zip

Query up to 100 ZIP codes in a single request. Returns an array of full water quality objects. Pro and Enterprise only.

Body Parameter	Type	Description
`zips`	`string[]`	Array of 5-digit ZIP codes (max 100)
`fields`	`string[]`	Optional. Fields to include (e.g., `["score","grade","contaminants"]`)

Example request:

curl -X POST https://api.zipcheckup.com/v1/bulk/zip \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zips": ["90210","10001","60601"]}'

Response Format

All responses are JSON with the following envelope:

// Success
{
  "ok": true,
  "data": { ... },
  "meta": {
    "dataDate": "2026-03-19",
    "requestId": "req_abc123"
  }
}

// Error
{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No data found for ZIP 00000"
  }
}

Pro tier can request CSV format by adding ?format=csv to any GET endpoint.

Error Codes

HTTP Status	Error Code	Description
400	`BAD_REQUEST`	Invalid parameters (e.g., malformed ZIP code)
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Endpoint requires a higher plan (e.g., bulk on Free tier)
404	`NOT_FOUND`	No data for the requested resource
429	`RATE_LIMITED`	Rate limit exceeded. Check `X-RateLimit-Reset` header
500	`INTERNAL_ERROR`	Something went wrong on our end

Versioning

The API is versioned via the URL path (/v1/). We will not make breaking changes within a version. New fields may be added to responses at any time — your code should handle unknown fields gracefully.

When a new version is released, the previous version will be supported for at least 12 months.

Get Your API Key