En esta página

Descripción general
Autenticación
01 · Códigos Postales
02 · Colonias
03 · Estados
04 · Municipios
05 · Localidades
06 · Calles
07 · Geocodificación
08 · Cuenta
Límites y Errores

Sincronizado del catálogo oficial de SEPOMEX

Referencia de API

Acceso programático al catálogo oficial de SEPOMEX: códigos postales, colonias, municipios, estados, localidades y calles. Cada respuesta es JSON, cada solicitud lleva un solo token Bearer.

URL base https://api.postalkit.mx

códigos postales: 31,874
colonias: 157,932
municipios: 2,478
estados: 32

Autenticación

Cada solicitud debe incluir tu token de API en el encabezado Authorization. Genera un token desde tu panel después de registrarte.

Authorization

Authorization: Bearer YOUR_API_KEY

Las solicitudes sin un token válido devuelven 401 Unauthorized .

Endpoints

Todas las rutas de abajo son relativas a la URL base. Los segmentos entre {llaves} son parámetros de ruta requeridos.

01/5 endpoints

Códigos Postales

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 coordenadas geográficas. Los parámetros opcionales de calle y número se incluyen en la respuesta como referencia pero no afectan las coordenadas devueltas.

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": "19.4233000",
    "longitude": "-99.1637000",
    "geocoded_street": "Reforma",
    "geocoded_number": "100"
  }
}

404 No Encontrado

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

02/1 endpoints

Colonias

GET /v1/settlements?q={name}

Búsqueda de Colonia

Busca colonias por nombre parcial. Devuelve una lista paginada con contexto de municipio y estado.

Parámetros de Consulta

Parámetro	Tipo	Descripción
q	string	Nombre parcial de colonia, mín. 2 caracteres. Ej. `Polanco`
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/settlements?q=Polanco&page=1"

Respuesta

200 Éxito

{
  "data": [
    {
      "id": 8421,
      "name": "Polanco I Sección",
      "type": "Colonia",
      "postal_code": "11510",
      "municipality": "Miguel Hidalgo",
      "state": "Ciudad de México"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 6, "per_page": 20 }
}

03/6 endpoints

Estados

GET /v1/states

Listar Estados

Devuelve todos los estados de México con sus IDs y códigos oficiales de SEPOMEX. Usa el id para consultar municipios.

Solicitud

curl

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

Respuesta

200 Éxito

{
  "data": [
    { "id": 2, "name": "Aguascalientes", "code": "01" },
    { "id": 1, "name": "Ciudad de México", "code": "09" }
  ]
}

GET /v1/states/{id}/municipalities

Listar Municipios por Estado

Devuelve todos los municipios de un estado dado. Obtén el id del estado de Listar Estados.

Parámetros de URL

Parámetro	Tipo	Descripción
id	integer	ID numérico del estado

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/1/municipalities

Respuesta

200 Éxito

{
  "data": [
    { "id": 1, "name": "Álvaro Obregón", "code": "010" },
    { "id": 6, "name": "Cuauhtémoc", "code": "015" }
  ]
}

404 Estado No Encontrado

{ "message": "State with id 999 not found." }

GET /v1/states/by-code/{code}/municipalities

Listar Municipios por Código INEGI

Devuelve todos los municipios que pertenecen al estado identificado por su código INEGI de 2 dígitos, ordenados alfabéticamente.

Parámetros de URL

Parámetro	Tipo	Descripción
code	string	Código INEGI de estado de 2 dígitos, ej. `09`

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/by-code/09/municipalities

Respuesta

200 Éxito

{
  "data": [
    { "id": 1, "name": "Álvaro Obregón", "code": "010" },
    { "id": 6, "name": "Cuauhtémoc", "code": "015" }
  ]
}

404 Estado No Encontrado

{ "message": "State with code '99' not found." }

GET /v1/states/{id}/cities

Listar Ciudades por Estado

Devuelve todas las ciudades que pertenecen al estado dado, ordenadas alfabéticamente.

Parámetros de URL

Parámetro	Tipo	Descripción
id	integer	ID numérico del estado

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/2/cities

Respuesta

200 Éxito

{
  "data": [
    { "id": 1, "name": "Aguascalientes" },
    { "id": 2, "name": "Calvillo" }
  ]
}

404 Estado No Encontrado

{ "message": "State with id 999 not found." }

GET /v1/states/{id}/postal-codes

Listar Códigos Postales por Estado

Devuelve todos los códigos postales que pertenecen al estado dado, ordenados por código y paginados.

Parámetros de URL

Parámetro	Tipo	Descripción
id	integer	ID numérico del estado

Solicitud

curl

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

Respuesta

200 Éxito (paginado)

{
  "data": [
    {
      "id": 1,
      "code": "20000",
      "state": { "id": 2, "name": "Aguascalientes", "code": "01" },
      "municipality": { "id": 1, "name": "Aguascalientes", "code": "001" },
      "city": { "id": 1, "name": "Aguascalientes" }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 100, "per_page": 20 }
}

404 Estado No Encontrado

{ "message": "State with id 999 not found." }

GET /v1/states/{id}/municipalities/{mid}/settlements

Listar Colonias por Municipio

Devuelve todas las colonias que pertenecen al municipio dado dentro del estado dado, ordenadas alfabéticamente y paginadas con 20 resultados por página.

Parámetros de URL

Parámetro	Tipo	Descripción
id	integer	ID numérico del estado
mid	integer	ID numérico del municipio

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/1/municipalities/6/settlements

Respuesta

200 Éxito (paginado)

{
  "data": [
    {
      "id": 532,
      "name": "Juárez",
      "zone": "Urbano",
      "settlement_type": { "id": 1, "name": "Colonia" },
      "postal_code": { "id": 384, "code": "06600" }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 33, "per_page": 20 }
}

404 No Encontrado

{ "message": "State with id 999 not found." }
{ "message": "Municipality with id 999 not found." }

04/2 endpoints

Municipios

GET /v1/municipalities/{id}/postal-codes

Listar Códigos Postales por Municipio

Devuelve todos los códigos postales que pertenecen al municipio dado, ordenados por código y paginados con 20 resultados por página.

Parámetros de URL

Parámetro	Tipo	Descripción
id	integer	ID numérico del municipio

Solicitud

curl

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

Respuesta

200 Éxito (paginado)

{
  "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" }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 71, "per_page": 20 }
}

404 No Encontrado

{ "message": "Municipality with id 999 not found." }

GET /v1/municipalities/{id}/settlements

Listar Colonias por Municipio

Devuelve todas las colonias que pertenecen al municipio dado, ordenadas alfabéticamente y paginadas con 20 resultados por página.

Parámetros de URL

Parámetro	Tipo	Descripción
id	integer	ID numérico del municipio

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/municipalities/6/settlements

Respuesta

200 Éxito (paginado)

{
  "data": [
    {
      "id": 532,
      "name": "Juárez",
      "zone": "Urbano",
      "settlement_type": { "id": 1, "name": "Colonia" },
      "postal_code": { "id": 384, "code": "06600" }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 230, "per_page": 20 }
}

404 No Encontrado

{ "message": "Municipality with id 999 not found." }

05/2 endpoints

Localidades

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

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/localities/1

Respuesta

200 Éxito

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

404 No Encontrado

{ "message": "Locality with id 99999 not found." }

06/2 endpoints

Calles

GET /v1/streets

Buscar Calles

Busca calles dentro de un estado y municipio. Opcionalmente filtra por localidad y nombre de calle. Devuelve resultados paginados ordenados por nombre.

Parámetros de Consulta

Parámetro	Tipo	Descripción
state_code	string	Código INEGI del estado (requerido). Ej. `09`
municipality_code	string	Código INEGI del municipio (requerido). Ej. `015`
locality_code	string	Código INEGI de localidad opcional para reducir resultados
q	string	Búsqueda opcional de nombre de calle (coincidencia parcial)
limit	integer	Resultados por página (máx. 100, predeterminado 50)
page	integer	Número de página

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/streets?state_code=09&municipality_code=015&q=Reforma"

Respuesta

200 Éxito (paginado)

{
  "data": [
    {
      "id": 1,
      "name": "Reforma",
      "code": "0001",
      "ambito": "Urbano",
      "street_type": { "id": 1, "name": "Avenida", "code": "01" },
      "state": { "id": 1, "name": "Ciudad de México", "code": "09" },
      "municipality": { "id": 6, "name": "Cuauhtémoc", "code": "015" }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "total": 1, "per_page": 50 }
}

422 Error de Validación

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

GET /v1/street-types

Listar Tipos de Calle

Obtiene el catálogo completo de tipos de calle (ej. Avenida, Calle, Boulevard). Devuelve todos los tipos ordenados por nombre.

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/street-types

Respuesta

200 Éxito

{
  "data": [
    { "id": 1, "name": "Avenida", "code": "01" },
    { "id": 2, "name": "Boulevard", "code": "02" },
    { "id": 3, "name": "Calle", "code": "03" }
  ]
}

07/1 endpoints

Geocodificación

GET /v1/geocode/reverse

Geocodificación Inversa

Encuentra el código postal más cercano a las coordenadas de latitud y longitud dadas.

Parámetros de Consulta

Parámetro	Tipo	Descripción
lat	number	Latitud (-90 a 90)
lng	number	Longitud (-180 a 180)

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/geocode/reverse?lat=19.4233&lng=-99.1637"

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": "19.4233000",
    "longitude": "-99.1637000"
  }
}

404 Sin Resultados

{ "message": "No geocoded postal codes found near the given coordinates." }

422 Error de Validación

{ "message": "The given data was invalid.", "errors": { "lat": ["The lat field is required."], "lng": ["The lng field is required."] } }

08/2 endpoints

Cuenta

GET /v1/account/usage

Uso de Cuenta

Obtiene tu plan actual, límite mensual de solicitudes, conteo de uso y solicitudes restantes para el período de facturación actual.

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/account/usage

Respuesta

200 Éxito

{
  "data": {
    "plan": "free",
    "monthly_limit": 100,
    "usage_count": 42,
    "remaining": 58,
    "period": "2026-05"
  }
}

GET /v1/account/db-version

Versión de Base de Datos

Obtiene la fecha de la última actualización de la base de datos SEPOMEX y la versión actual de la API.

Solicitud

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/account/db-version

Respuesta

200 Éxito

{
  "data": {
    "last_updated": "2026-03-15T00:00:00.000000Z",
    "version": "1.0.0"
  }
}

Límites y Errores

Cuotas Mensuales

Plan	Solicitudes / Mes
Free	100
Starter	5,000
Pro	50,000
Business	250,000

Consulta precios para los detalles de planes y precios mensuales.

Encabezados de Límite

Cada respuesta de la API incluye estos encabezados:

headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 58

Respuestas de Error

Estado	Significado
401 Unauthorized	Token de API faltante o inválido
404 Not Found	El recurso (código postal o estado) no existe
422 Unprocessable Entity	Entrada inválida, revisa el campo message para más detalles
429 Too Many Requests	Cuota mensual excedida

Referencia de API

Autenticación

Endpoints

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

Colonias

Búsqueda de Colonia

Parámetros de Consulta

Estados

Listar Estados

Listar Municipios por Estado

Parámetros de URL

Listar Municipios por Código INEGI

Parámetros de URL

Listar Ciudades por Estado

Parámetros de URL

Listar Códigos Postales por Estado

Parámetros de URL

Listar Colonias por Municipio

Parámetros de URL

Municipios

Listar Códigos Postales por Municipio

Parámetros de URL

Listar Colonias por Municipio

Parámetros de URL

Localidades

Buscar Localidades

Parámetros de Consulta

Obtener Localidad

Parámetros de URL

Calles

Buscar Calles

Parámetros de Consulta

Listar Tipos de Calle

Geocodificación

Geocodificación Inversa

Parámetros de Consulta

Cuenta

Uso de Cuenta

Versión de Base de Datos

Límites y Errores

¿Listo para construir?