Documentación

De cero a tu primera petición

Una API REST sobre el catálogo completo de Correos de México. Siete endpoints, una cabecera de autenticación y JSON plano. Esta guía cubre lo que necesitas para integrarla; la referencia completa, generada del código, está en api.pc-mex.jlpz.me/docs.

Paso 1

Crea una cuenta y genera una key

1.Crea tu cuenta y confirma el correo. No pide tarjeta.
2.En Panel → API keys genera una key. Se muestra una sola vez: cópiala y guárdala en una variable de entorno.
3.Mándala en la cabecera X-Api-Key en cada petición.

curl "https://api.pc-mex.jlpz.me/v1/postal-codes/01000" \
  -H "X-Api-Key: $PCMEX_API_KEY"

200 OK · 8 ms al percentil 95

Paso 2

Autenticación

Las keys tienen el formato pcmx_live_… y viajan en la cabecera X-Api-Key. En nuestra base sólo se guarda su hash y los primeros caracteres, así que si la pierdes no podemos recuperarla: rótala desde el panel y la anterior deja de funcionar al instante.

Una key es un secreto de servidor. No la pongas en código de navegador ni en una app móvil: quien vea tu bundle puede gastarse tu cuota. Si necesitas consultar desde el navegador, haz la llamada desde tu backend.

Sin cabecera también se puede consultar, pero el tráfico anónimo está limitado a 30 peticiones por minuto y por IP: sirve para probar, no para producción.

Referencia

Endpoints

Ruta	Qué devuelve
GET /v1/postal-codes/{cp}	Estado, municipio, oficina postal y colonias del código.404 si el código no existe en el catálogo.
GET /v1/search	Busca colonias por nombre; tolera acentos, mayúsculas y erratas.Parámetros: q (obligatorio), state, municipality, limit, offset.
GET /v1/validate	Comprueba que el código existe y, si mandas colonia, cuál es la que mejor coincide.Parámetros: cp (obligatorio), settlement.
GET /v1/states	Los 32 estados con su número de municipios y de códigos postales.Respuesta pequeña y muy cacheable: ideal para poblar un select.
GET /v1/states/{state}/municipalities	Municipios y alcaldías de un estado.{state} es la clave de dos dígitos que devuelve /v1/states.
GET /v1/municipalities/{state}/{code}/postal-codes	Códigos postales de un municipio.Útil para validar una dirección contra un municipio ya elegido.
GET /v1/meta	Versión y fecha del catálogo, conteos y fuentes.Consúltalo si guardas datos en tu propia base y quieres saber cuándo refrescar.

Hay además un GET /health sin autenticación para tus alertas, y el OpenAPI 3.1 completo en /openapi.json, con el que puedes generar un cliente en tu lenguaje.

Caso de uso

Autocompletar una colonia

El uso más común es un formulario de envío: la persona escribe su colonia como la escribe siempre —sin acentos, con abreviaturas, con alguna errata— y hay que encontrarla. /v1/search normaliza el texto y ordena por parecido, así que «alvaro obregon» llega a «Álvaro Obregón».

curl "https://api.pc-mex.jlpz.me/v1/search?q=alvaro+obregon&limit=5" \
  -H "X-Api-Key: $PCMEX_API_KEY"

200 OK · 46 ms al percentil 95 sobre 159,201 colonias

Dos consejos: cancela la petición anterior con AbortController mientras la persona sigue escribiendo, y espera a que haya escrito tres caracteres antes de la primera consulta. Con eso un autocompletado normal gasta muchas menos peticiones de las que parece.

Referencia

Errores

Todos los errores tienen la misma forma, así que puedes manejarlos en un solo lugar:

{ "error": { "code": "quota_exceeded", "message": "Cuota mensual agotada" } }

HTTP	code	Cuándo pasa	Qué hacer
400	validation_error	Un parámetro falta o no tiene la forma esperada.	El campo message dice cuál. Revisa el nombre y el tipo antes de reintentar.
401	invalid_api_key	La key no existe, está revocada o el formato no es el correcto.	Genera una nueva desde tu panel. Reintentar con la misma no va a funcionar.
404	not_found	El código postal, estado o municipio no está en el catálogo.	No es un error del servicio: ese dato no existe. No reintentes.
429	rate_limited	Superaste las peticiones por segundo de tu plan.	Espera los segundos que indica Retry-After y vuelve a intentar.
429	quota_exceeded	Se acabaron las peticiones incluidas del mes.	Sube de plan o espera al siguiente mes calendario. Reintentar antes da el mismo error.
500	internal_error	Algo falló de nuestro lado.	Reintenta con espera creciente. Si persiste, escríbenos con la hora aproximada.

Referencia

Límites y cuotas

Plan	Peticiones/mes	Por segundo	Keys activas
Gratis	1,000	2	1
Starter	50,000	10	5
Pro	500,000	50	100

Cada respuesta trae X-Quota-Limit, X-Quota-Used y X-Quota-Remaining, así que puedes vigilar el consumo sin abrir el panel. Cuando se agota, la API responde 429 quota_exceeded hasta el siguiente mes calendario; te avisamos por correo al 80 % y al 100 %.

El rate limit por segundo es una ventana deslizante y responde 429 rate_limited con Retry-After. Ese sí conviene reintentarlo, con espera creciente.

Buenas prácticas

Caché y ETag

El catálogo cambia unas cuantas veces al año, así que casi todo se puede guardar. Toda respuesta trae Cache-Control y ETag: si mandas el ETag en If-None-Match y el dato no cambió, recibes un 304 sin cuerpo que no consume cuota.

curl "https://api.pc-mex.jlpz.me/v1/states" \
  -H "X-Api-Key: $PCMEX_API_KEY" \
  -H 'If-None-Match: W/"a1b2c3"' -i

HTTP/1.1 304 Not Modified

Los catálogos geográficos —estados y municipios— casi nunca cambian: guárdalos en tu propia base y refresca cuando /v1/meta reporte una versión nueva.

Contexto

Sobre los datos

La versión en línea es la del 4 de septiembre de 2026, con 159,201 colonias, 31,875 códigos postales y 2,478 municipios. Puedes verificarlo tú mismo en la página de estado o en /v1/meta.

Un detalle que sorprende al integrar: un código postal puede tener varias colonias —el 97000 de Mérida tiene ocho— y en ese caso hay que dejar que la persona elija. Por eso /v1/postal-codes/{cp} devuelve siempre una lista, aunque traiga un solo elemento.

Origen, licencia y obligaciones de atribución están en fuentes y atribución.