API de localidades

Busca localidades de México por nombre y consulta una localidad con el municipio y el estado a los que pertenece. Estos endpoints están activos, pero el catálogo de localidades que va detrás todavía no está cargado.

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

Todos los endpoints de esta página están desplegados y responden, pero el catálogo que va detrás no está cargado, así que los resultados vuelven vacíos. Las formas de solicitud y respuesta de abajo son el contrato y no van a cambiar cuando lleguen los datos. Nada más de la API se ve afectado.

URL base https://api.postalkit.mx

Autenticación

GET /v1/localities

Buscar Localidades

Busca localidades dentro de un estado y municipio. Soporta dos modos de filtro: por nombre (estado + municipio) con búsqueda difusa, o por código INEGI (state_code + municipality_code) con búsqueda exacta. Devuelve resultados paginados ordenados por nombre.

Parámetros de Consulta

Parámetro	Tipo	Descripción
state	string	Nombre del estado (búsqueda difusa). Requerido si no se usan códigos.
municipality	string	Nombre del municipio (búsqueda difusa). Requerido si no se usan códigos.
state_code	string	Código INEGI del estado. Requerido si no se usan nombres.
municipality_code	string	Código INEGI del municipio. Requerido si no se usan nombres.
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/localities?state=Jalisco&municipality=Guadalajara"

Respuesta

200 Éxito (paginado)

{
  "data": [
    {
      "id": 1,
      "locality_code": "0001",
      "name": "Guadalajara",
      "ambito": "Urbano",
      "latitude": "20.6737800",
      "longitude": "-103.3442300",
      "altitude": "1566",
      "state": { "id": 14, "name": "Jalisco", "code": "14" },
      "municipality": { "id": 39, "name": "Guadalajara", "code": "039" }
    }
  ],
  "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": { "filter": ["You must provide either (state and municipality) or (state_code and municipality_code)."] } }

GET /v1/localities/{id}

Obtener Localidad

Obtiene una localidad por su ID, incluyendo detalles de estado y municipio.

Parámetros de URL

Parámetro	Tipo	Descripción
id	integer	El ID de la localidad