Ir al contenido

Código postal con todos sus asentamientos

GET/v1/postal-codes/{code}Todos los planes

¿Qué hace?

Todo sobre un código postal: su estado, su municipio y todos sus asentamientos (colonias, fraccionamientos, barrios...). Úsalo para llenar un formulario de dirección en cuanto el usuario escribe su código postal.

Regresa todos los asentamientos (sin paginar; el código postal más grande tiene 291). Bloques opcionales con include: location (punto de referencia), metro (zona metropolitana) y sat (claves del SAT para CFDI 4.0) en los planes de pago; los códigos postales de demostración dan los tres bloques en todos los planes. Un código postal que no existe responde 404 /errors/postal-code-not-found, que no cuenta para tu cuota.

Con as_of obtienes el código postal como lo tenía SEPOMEX en una fecha pasada: sus asentamientos de ese día, según el archivo de SEPOMEX más reciente de esa fecha o anterior (as_of.sepomex_date). Sirve para revisar una dirección que se capturó o se facturó entonces. Las fechas van desde history_since (ver /v1/meta) hasta hoy; una anterior responde 400 /errors/as-of-out-of-range, porque no hay registro de lo que decía el catálogo antes. Un código postal que no existía en esa fecha responde 404. include no se combina con as_of.

La petición

ParámetroTipoValores aceptadosDescripción
codeen la rutaobligatoriotexto
5 dígitos
Código postal de 5 dígitos.
fieldsen la consultalista de textoseparados por comas
postal_codestatemunicipalityofficesettlement_countsettlementsdata_versionsatlocationmetro_areaas_of
Campos de primer nivel a regresar, separados por comas. Permitidos: postal_code, state, municipality, office, settlement_count, settlements, data_version, sat (con include=sat), location (con include=location), metro_area (con include=metro) y as_of (con as_of).
includeen la consultalista de textoseparados por comas
satlocationmetro
Bloques opcionales a agregar, separados por comas (sat,location,metro). sat: datos del SAT para CFDI 4.0; requiere un plan de pago. location: ubicación de referencia del código postal; requiere un plan de pago. metro: zona metropolitana del código postal; requiere un plan de pago. Los códigos postales de demostración en /v1/postal-codes/{code} dan los tres bloques en todos los planes.
as_ofen la consultafecha—Fecha (AAAA-MM-DD) para obtener el código postal como lo tenía SEPOMEX ese día, desde history_since (ver /v1/meta) hasta hoy en la Ciudad de México. No se combina con include.

Ejemplo

curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/postal-codes/06700"

Cambia TU_LLAVE por tu llave; en los lenguajes, se lee de la variable de entorno COLONIX_API_KEY. Esta petición es la que produjo la respuesta de abajo.

La respuesta

Respuesta real a la petición del ejemplo. Viene con los encabezados ETag, X-Data-Version, Cache-Control.

200 OK
{
"postal_code": "06700",
"state": {
"id": "09",
"name": "Ciudad de México"
},
"municipality": {
"id": "015",
"name": "Cuauhtémoc"
},
"office": "06401",
"settlement_count": 1,
"settlements": [
{
"id": "09015-0947",
"name": "Roma Norte",
"type": "Colonia",
"zone": "Urbano",
"city": "Ciudad de México"
}
],
"data_version": "2026.11.05-36a7823b"
}

Campos

CampoTipoDescripción
postal_codetextoCódigo postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700).
stateobjetoElemento de un catálogo.
state.idtextoClave oficial
state.nametextoNombre
municipalityobjetoElemento de un catálogo.
municipality.idtextoClave oficial
municipality.nametextoNombre
officetextoOficina postal que atiende el código
settlement_countenteroNúmero de asentamientos
satno siempre vieneobjetoDatos del SAT de un código postal (CFDI 4.0 y Carta Porte).
sat.in_satbooleanoEl código postal está en c_CodigoPostal (válido para CFDI)
sat.in_sepomexbooleanoEl código postal está en el catálogo de SEPOMEX
sat.stateobjeto o nullClave del estado en el SAT y en el INEGI, o null si no está en el SAT
sat.municipalityobjeto o nullClave del SAT con su nombre, o null
sat.localityobjeto o nullClave del SAT con su nombre, o null
sat.border_stimulustexto o nullEstímulo fiscal de la región fronteriza: north (norte), south (sur) o null. El código postal no basta para aplicarlo: ver border_stimulus_decree
northsouth
sat.border_stimulus_decreeobjeto o nullVigencia del decreto del estímulo fiscal de la región fronteriza, o null si el código postal no está en una región fronteriza. El contribuyente debe presentar un aviso ante el SAT (requires_sat_notice) y cumplir sus requisitos; después de valid_until el estímulo deja de aplicar, salvo que un decreto nuevo lo prorrogue
sat.time_zoneobjeto o nullHuso horario como lo publica el SAT, más el huso real (iana y sus diferencias con UTC), o null si no está en el SAT. En las franjas fronterizas de Chihuahua el SAT sigue la letra de la ley de husos horarios y difiere de la hora que se usa en la práctica (matches_sat: false)
sat.settlementslista de objetosColonias del SAT (c_Colonia) del código postal
sat.settlements_missing_in_satlista de objetosAsentamientos de SEPOMEX del código postal sin clave del SAT: ninguna colonia del SAT tiene el mismo nombre ni uno equivalente, o las que lo tienen ya son de otro asentamiento con ese nombre
sat.sat_revisionobjetoVersión del archivo de catálogos del SAT que se usó.
locationno siempre vieneobjeto o nullCon include=location: ubicación de referencia, o null si no hay
location.latnúmeroLatitud (WGS84), con 6 decimales como máximo
location.lonnúmeroLongitud (WGS84), con 6 decimales como máximo
location.bboxlista de número o null[oeste, sur, este, norte] en grados, o null para una localidad
location.precisiontextoDe dónde sale el punto
postal_code_polygonlocality_centroidmunicipality_centroid
location.source_datefechaFecha del dato de la fuente
metro_areano siempre vieneobjeto o nullCon include=metro: zona metropolitana del municipio, o null si no está en ninguna
metro_area.idtextoClave oficial de la metrópoli
metro_area.nametextoNombre de la metrópoli
metro_area.typetextoTipo tal como se publica (en español)
Zona metropolitanaMetrópoli municipalZona conurbada
metro_area.municipality_roletextoSi el municipio del código postal es central o exterior en la metrópoli
centralexterior
settlementslista de objetosAsentamientos del código postal
settlements[].idtextoClave del asentamiento: no cambia cuando SEPOMEX le cambia el nombre o lo mueve a otro código postal, así que guarda también el nombre y el código postal
settlements[].nametextoNombre del asentamiento
settlements[].typetextoTipo de asentamiento
settlements[].zonetextoZona
UrbanoRuralSemiurbano
settlements[].citytexto o nullCiudad, o null si no tiene
data_versiontextoVersión del dato

Campos con as_of

Un código postal como lo tenía SEPOMEX en la fecha as_of.

CampoTipoDescripción
postal_codetextoCódigo postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700).
stateobjetoElemento de un catálogo.
state.idtextoClave oficial
state.nametextoNombre
municipalityobjetoElemento de un catálogo.
municipality.idtextoClave oficial
municipality.nametextoNombre
officetextoOficina postal que atendía el código
settlement_countenteroNúmero de asentamientos en esa fecha
settlementslista de objetosAsentamientos en esa fecha, por nombre
settlements[].idtextoClave del asentamiento
settlements[].nametextoNombre del asentamiento
settlements[].typetextoTipo de asentamiento
settlements[].zonetextoZona
UrbanoRuralSemiurbano
settlements[].citytexto o nullCiudad, o null si no tiene
as_ofobjetoEn qué se basa la respuesta
as_of.datefechaLa fecha que pediste
as_of.sepomex_datefechaFecha del archivo de SEPOMEX que da la respuesta: el más reciente de esa fecha o anterior
as_of.data_versiontextoVersión del dato que publicó ese archivo
data_versiontextoVersión del dato de esta respuesta (la vigente)

Errores

Todos en formato application/problem+json; ninguno cuenta para tu cuota. Qué hacer con cada uno: Errores.

EstadoCuándo
400Parámetro inválido o repetido (/errors/invalid-parameter), un parámetro que el endpoint no tiene (/errors/unknown-parameter), cursor vencido (/errors/cursor-expired), versión del dato desconocida (/errors/unknown-version) o as_of fuera del historial registrado (/errors/as-of-out-of-range).
401Credenciales faltantes (/errors/missing-api-key) o inválidas (/errors/invalid-api-key).
403Llave suspendida (/errors/api-key-suspended) o endpoint fuera de tu plan (/errors/plan-not-allowed).
404El recurso no existe (/errors/postal-code-not-found, /errors/state-not-found, /errors/municipality-not-found, /errors/location-not-covered o /errors/route-not-found). No cuenta para tu cuota.
429Se alcanzó la cuota mensual (/errors/quota-exceeded) o el límite por minuto (/errors/rate-limited). La respuesta del límite por minuto trae el mismo cuerpo, pero con Content-Type: application/json.
5XXError inesperado (/errors/internal-error) o servicio no disponible por un momento (503, que puede llegar sin cuerpo). Reintenta unas cuantas veces, esperando cada vez más.