Documentación de la API

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

Autenticación

Todas las solicitudes requieren una API key enviada en el encabezado X-API-Key.

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

Obtenga una API key gratis en /api/pricing/. No se necesita tarjeta de crédito.

Límites de uso

Plan gratuito: 100 solicitudes por día por dirección IP. El límite diario se reinicia a la medianoche UTC.

Plan	Límite diario
Gratis	100 solicitudes/día
Pro ($49/mes)	10,000 solicitudes/día
Enterprise	Personalizado

Los encabezados de límite de uso se incluyen en cada respuesta de la API:

Encabezado	Descripción
`X-RateLimit-Limit`	Máximo de solicitudes permitidas por día (por ejemplo, `100`)
`X-RateLimit-Remaining`	Solicitudes restantes en la ventana actual
`X-RateLimit-Reset`	Marca de tiempo Unix cuando se reinicia el límite (medianoche UTC)

Encabezados de ejemplo:

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

Cuando supere el límite, recibirá una respuesta 429 Too Many Requests con una URL de upgrade:

{
  "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/"
}

¿Necesita más de 100 solicitudes/día? Vea opciones con límites más altos.

Endpoints

Obtener datos de calidad del agua por código postal

GET /v1/zip/{zip}

Devuelve los datos completos de calidad del agua para un código postal de EE. UU., incluyendo puntaje de seguridad, contaminantes, infracciones y sistemas de agua.

Parámetro	Tipo	Descripción
`zip`	string	Código postal de EE. UU. de 5 dígitos (parámetro de ruta)

Respuesta de ejemplo:

{
  "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": [...]
}

Obtener solo el puntaje de seguridad

GET /v1/zip/{zip}/score

Devuelve solo el puntaje de seguridad, la calificación y el nivel de riesgo. Respuesta más ligera para paneles y widgets.

Respuesta de ejemplo:

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

Obtener resumen del estado

GET /v1/state/{state}

Devuelve un resumen para un estado de EE. UU.: puntaje promedio, cantidad de códigos postales, principales infracciones y los códigos postales con peor puntaje.

Parámetro	Tipo	Descripción
`state`	string	Abreviatura de 2 letras del estado (por ejemplo, `CA`, `NY`, `TX`)

Respuesta de ejemplo:

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

Obtener ranking nacional

GET /v1/rankings

Devuelve una lista de códigos postales ordenada por puntaje de calidad del agua.

Parámetro	Tipo	Por defecto	Descripción
`limit`	integer	50	Cantidad de resultados (máximo 500)
`order`	string	`desc`	`desc` = mejores primero, `asc` = peores primero
`state`	string	todos	Filtrar por código de estado de 2 letras

Obtener referencia de contaminante

GET /v1/contaminant/{code}

Devuelve información de referencia sobre un contaminante: nombre, MCL de la EPA, efectos en la salud y fuentes comunes.

Parámetro	Tipo	Descripción
`code`	string	Código del contaminante (de la respuesta del endpoint de código postal)

Consulta masiva de códigos postales Pro+

POST /v1/bulk/zip

Acceso a hasta 100 códigos postales en una sola solicitud. Devuelve un arreglo de objetos completos de calidad del agua. Disponible solo en Pro y Enterprise.

Parámetro del cuerpo	Tipo	Descripción
`zips`	`string[]`	Arreglo de códigos postales de 5 dígitos (máximo 100)
`fields`	`string[]`	Opcional. Campos a incluir (por ejemplo, `["score","grade","contaminants"]`)

Solicitud de ejemplo:

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"]}'

Formato de respuesta

Todas las respuestas son JSON con la siguiente envoltura:

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

// Error
{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No se encontraron datos para el código postal 00000"
  }
}

El plan Pro puede solicitar el formato CSV agregando ?format=csv a cualquier endpoint GET.

Códigos de error

Estado HTTP	Código de error	Descripción
400	`BAD_REQUEST`	Parámetros inválidos (por ejemplo, código postal con formato incorrecto)
401	`UNAUTHORIZED`	API key ausente o inválida
403	`FORBIDDEN`	El endpoint requiere un plan superior (por ejemplo, consulta masiva en el plan gratuito)
404	`NOT_FOUND`	No hay datos para el recurso solicitado
429	`RATE_LIMITED`	Límite de uso excedido. Vea el encabezado `X-RateLimit-Reset`
500	`INTERNAL_ERROR`	Algo falló de nuestro lado

Versionado

La API se versiona mediante la ruta de la URL (/v1/). No haremos cambios incompatibles dentro de una misma versión. Se pueden agregar nuevos campos a las respuestas en cualquier momento — su código debe manejar los campos desconocidos sin fallar.

Cuando se publique una nueva versión, la versión anterior tendrá soporte durante al menos 12 meses.

Obtenga su API key