01/5 endpoints

API de códigos postales

Consulta cualquier código postal de México y obtén su estado, municipio, ciudad y colonias. Busca por prefijo numérico, o por estado, municipio y nombre de colonia, y lista los asentamientos de un solo código.

URL base https://api.postalkit.mx

Autenticación

Consulta de Código Postal
Búsqueda por Prefijo
Búsqueda por Geografía
Colonias por Código
Geocodificar por Código

GET /v1/postal-codes/{code}

Consulta de Código Postal

Devuelve el registro completo de un código postal de 5 dígitos, incluyendo su estado, municipio, ciudad y todas las colonias.

Parámetros de URL

Parámetro	Tipo	Descripción
code	string	Código postal de 5 dígitos, ej. `06600`

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/postal-codes/06600

Respuesta

200 Éxito

{
  "data": {
    "id": 384,
    "code": "06600",
    "state": { "id": 1, "name": "Ciudad de México", "code": "09" },
    "municipality": { "id": 6, "name": "Cuauhtémoc", "code": "015" },
    "city": { "id": 1, "name": "Ciudad de México" },
    "settlements": [
      { "id": 532, "name": "Juárez", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
    ]
  }
}

404 No Encontrado

{ "message": "Postal code '99999' not found." }

GET /v1/postal-codes?q={prefix}

Buscar Códigos Postales por Prefijo

Busca códigos postales por prefijo numérico (útil para autocompletado). Devuelve resultados paginados ordenados por código. La consulta debe tener al menos 2 caracteres.

Parámetros de Consulta

Parámetro	Tipo	Descripción
q	string	Prefijo numérico, mín. 2 caracteres. Ej. `066`
page	integer	Número de página (20 resultados por página, predeterminado 1)

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/postal-codes?q=066&page=1"

Respuesta

200 Éxito (paginado)

{
  "data": [ ... ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 85, "per_page": 20 }
}

422 Error de Validación

{ "message": "Query parameter \"q\" must be at least 2 characters." }

GET /v1/postal-codes/search

Buscar Códigos Postales por Geografía

Busca códigos postales usando filtros geográficos. Soporta búsqueda difusa (LIKE) y exacta mediante el parámetro exact. Devuelve resultados paginados ordenados por código.

Parámetros de Consulta

Parámetro	Tipo	Descripción
state	string	Nombre del estado a buscar (requerido). Ej. `Jalisco`
municipality	string	Filtro opcional de nombre de municipio. Ej. `Guadalajara`
colonia	string	Filtro opcional de nombre de colonia. Ej. `Centro`
exact	boolean	Usar búsqueda exacta en lugar de difusa (predeterminado: false)
page	integer	Número de página (20 resultados por página, predeterminado 1)

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/postal-codes/search?state=Jalisco&municipality=Guadalajara&colonia=Centro"

Respuesta

200 Éxito (paginado)

{
  "data": [
    {
      "id": 3,
      "code": "44100",
      "state": { "id": 14, "name": "Jalisco", "code": "14" },
      "municipality": { "id": 39, "name": "Guadalajara", "code": "039" },
      "city": { "id": 1, "name": "Guadalajara" },
      "settlements": [
        { "id": 5, "name": "Guadalajara Centro", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "total": 1, "per_page": 20 }
}

422 Error de Validación

{ "message": "The given data was invalid.", "errors": { "state": ["The \"state\" query parameter is required."] } }

GET /v1/postal-codes/{code}/settlements

Colonias de un Código Postal

Obtiene todas las colonias que pertenecen a un código postal de 5 dígitos. Devuelve una respuesta ligera sin los detalles completos del código postal.

Parámetros de URL

Parámetro	Tipo	Descripción
code	string	Código postal de 5 dígitos, ej. `06600`

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/postal-codes/06600/settlements

Respuesta

200 Éxito

{
  "data": [
    {
      "id": 532,
      "name": "Juárez",
      "zone": "Urbano",
      "settlement_type": { "id": 1, "name": "Colonia" }
    }
  ]
}

404 No Encontrado

{ "message": "Postal code '99999' not found." }

GET /v1/postal-codes/{code}/geocode

Geocodificar por Código Postal

Obtiene el registro completo de un código postal de 5 dígitos con sus coordenadas geográficas. Los parámetros opcionales street y number se devuelven en la respuesta como referencia, pero no afectan las coordenadas.

Todavía no hay datos detrás de este endpoint

Ningún código postal del catálogo trae coordenadas todavía, así que este endpoint responde 200 con el registro que pediste y latitude y longitude en null. Todo lo demás de la respuesta es real. Si lo que necesitas es el estado, el municipio y las colonias de un código sin la geocodificación, usa el endpoint de consulta de arriba.

Parámetros de URL

Parámetro	Tipo	Descripción
code	string	Código postal de 5 dígitos, ej. `06600`

Parámetros de Consulta

Parámetro	Tipo	Descripción
street	string	Nombre de calle opcional como referencia
number	string	Número de calle opcional como referencia

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/postal-codes/06600/geocode?street=Reforma&number=100"

Respuesta

200 Éxito

{
  "data": {
    "id": 384,
    "code": "06600",
    "state": { "id": 1, "name": "Ciudad de México", "code": "09" },
    "municipality": { "id": 6, "name": "Cuauhtémoc", "code": "015" },
    "city": null,
    "settlements": [],
    "latitude": null,
    "longitude": null,
    "geocoded_street": "Reforma",
    "geocoded_number": "100"
  }
}

404 No Encontrado

{ "message": "Postal code '99999' not found." }

API de códigos postales

Consulta de Código Postal

Parámetros de URL

Buscar Códigos Postales por Prefijo

Parámetros de Consulta

Buscar Códigos Postales por Geografía

Parámetros de Consulta

Colonias de un Código Postal

Parámetros de URL

Geocodificar por Código Postal

Parámetros de URL

Parámetros de Consulta

¿Listo para construir?