Cliente Python — copomex-py-client

Cliente oficial para Python 3.10+. Única dependencia externa: requests. Excepciones tipadas, nombres de métodos en snake_case.

Paquete PyPI: pypi.org/project/copomex-py-client

Instalación

pip install copomex-py-client

Inicio rápido

from copomex import Copomex
 
client = Copomex("TU_TOKEN")
 
info = client.info_cp("06600", simplified=True)
print(info)

Usa "pruebas" como token para desarrollo — sin costo, sin registro. Devuelve datos aleatorios con estructura real.

Constructor

Copomex(token: str, timeout: int = 10)

Manejo de errores

from copomex import Copomex, CopomexAPIError, CopomexHTTPError
 
client = Copomex("TU_TOKEN")
 
try:
    result = client.info_cp("99999")
except CopomexAPIError as e:
    # La API respondió con error: true
    print(f"[{e.code}] {e.message}")
except CopomexHTTPError as e:
    # Respuesta HTTP no exitosa (4xx, 5xx)

Referencia de métodos

Códigos postales

info_cp(cp, *, simplified=False)

Información completa de un código postal. Sin simplified, devuelve una lista (un elemento por colonia del CP). Con simplified=True, devuelve un dict con datos agregados.

colonias = client.info_cp("06600")                  # list[dict]
info     = client.info_cp("06600", simplified=True) # dict

search_cp(texto, *, limit=None)

Búsqueda por coincidencia parcial de código postal.

client.search_cp("066")
client.search_cp("066", limit=10)

get_colonia_por_cp(cp)

Colonias asociadas a un código postal.

client.get_colonia_por_cp("06600")

get_cp_por_estado(estado)

Todos los códigos postales de un estado.

client.get_cp_por_estado("Jalisco")

get_cp_por_municipio(municipio)

Códigos postales de un municipio.

client.get_cp_por_municipio("Guadalajara")

search_cp_advanced(estado, *, limit=None, municipio=None, colonia=None)

Búsqueda avanzada con filtros opcionales. Usa coincidencia parcial.

client.search_cp_advanced("Jalisco", municipio="Guadalajara", limit=20)
client.search_cp_advanced("CDMX", colonia="Condesa")

get_cp_advanced(estado, *, limit=None, municipio=None, colonia=None)

Igual que search_cp_advanced pero con coincidencia exacta.

client.get_cp_advanced("Jalisco", municipio="Guadalajara")

Estados

get_estados()

Lista de todos los estados de México.

client.get_estados()

get_estado_clave()

Estados con su clave oficial INEGI.

client.get_estado_clave()

Municipios

get_municipio_por_estado(estado)

Municipios de un estado.

client.get_municipio_por_estado("Jalisco")

get_municipio_clave_por_estado(estado)

Municipios con clave INEGI filtrados por nombre de estado.

client.get_municipio_clave_por_estado("Jalisco")

get_municipio_clave_por_clave_estado(clave)

Municipios con clave INEGI filtrados por clave de estado.

client.get_municipio_clave_por_clave_estado("14")

Colonias

get_colonia_por_municipio(municipio)

Colonias de un municipio.

client.get_colonia_por_municipio("Guadalajara")

get_colonia_por_estado_municipio(estado, municipio)

Colonias con CP filtradas por estado y municipio.

client.get_colonia_por_estado_municipio("Jalisco", "Guadalajara")

Ciudades

get_cities_by_state_code(clave_estado)

Ciudades de un estado por su clave INEGI.

client.get_cities_by_state_code("14")

Localidades

get_localidad_por_estado_municipio(estado, municipio)

Catálogo de localidades filtrado por nombre de estado y municipio.

client.get_localidad_por_estado_municipio("Jalisco", "Guadalajara")

get_localidad_por_clave_estado_municipio(clave_estado, clave_municipio)

Localidades filtradas por claves INEGI.

client.get_localidad_por_clave_estado_municipio("14", "039")

info_localidad(clave_estado, clave_municipio, clave_localidad)

Información detallada de una localidad. Incluye coordenadas y altitud.

client.info_localidad("14", "039", "0001")

Vialidades

get_vialidad(clave_estado, clave_municipio, busqueda, limit, *, clave_localidad=None)

Búsqueda en el catálogo de más de 3 millones de calles y vialidades.

client.get_vialidad("14", "039", "juarez", 10)
client.get_vialidad("14", "039", "reforma", 5, clave_localidad="0001")

get_tipo_vialidad()

Catálogo de los 22 tipos de vialidad (calle, avenida, boulevard, etc.).

client.get_tipo_vialidad()

Geocoding

Estos métodos consumen 2 créditos por consulta.

info_cp_geocoding(cp, *, type=None, calle=None, numero=None)

Convierte un código postal (con calle y número opcionales) a coordenadas lat/lng.

client.info_cp_geocoding("06600")
client.info_cp_geocoding("06600", calle="Insurgentes", numero="123")

info_cp_geocoding_reverse(lat, lng)

Convierte coordenadas lat/lng a dirección postal completa.

client.info_cp_geocoding_reverse(19.4326, -99.1332)

Cuenta

consultas_disponibles()

Saldo de créditos disponibles del token.

client.consultas_disponibles()

ultima_actualizacion_db()

Fecha y hora de la última actualización de la base de datos.

client.ultima_actualizacion_db()

Ejemplo completo

El archivo example/example.py del repositorio llama a los 24 endpoints con token=pruebas.

# Instalar en modo desarrollo desde la raíz del paquete
pip install -e .
 
# Ejecutar el ejemplo
python example/example.py