Cliente Node.js — copomex-node-client

Cliente oficial para Node.js 18+. Usa fetch nativo, sin dependencias de producción. Incluye tipos TypeScript y salida dual ESM + CommonJS.

Instalación

npm install copomex-node-client

Inicio rápido

// ESM
import { Copomex } from 'copomex-node-client';
 
// CommonJS
const { Copomex } = require('copomex-node-client');
 
const client = new Copomex('TU_TOKEN');
 
const info = await client.infoCP('06600', { simplified: true });
console.log(info);

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

Constructor

new Copomex(token: string, options?: { timeout?: number })

Manejo de errores

import { Copomex, CopomexAPIError, CopomexHTTPError } from 'copomex-node-client';
 
const client = new Copomex('TU_TOKEN');
 
try {
  const result = await client.infoCP('99999');
} catch (err) {
  if (err instanceof CopomexAPIError) {
    // La API respondió con error: true
    console.error(`[${err.code

Referencia de métodos

Códigos postales

infoCP(cp, options?)

Información completa de un código postal. Sin simplified, devuelve un array (una entrada por colonia). Con simplified: true, devuelve un objeto con datos agregados.

const colonias = await client.infoCP('06600');                       // array
const info     = await client.infoCP('06600', { simplified: true }); // object

searchCP(texto, options?)

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

await client.searchCP('066');
await client.searchCP('066', { limit: 10 });

getColoniaPorCP(cp)

Colonias asociadas a un código postal.

await client.getColoniaPorCP('06600');

getCPPorEstado(estado)

Todos los códigos postales de un estado.

await client.getCPPorEstado('Jalisco');

getCPPorMunicipio(municipio)

Códigos postales de un municipio.

await client.getCPPorMunicipio('Guadalajara');

searchCPAdvanced(estado, options?)

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

await client.searchCPAdvanced('Jalisco', { municipio: 'Guadalajara', limit: 20 });
await client.searchCPAdvanced('CDMX', { colonia: 'Condesa' });

getCPAdvanced(estado, options?)

Igual que searchCPAdvanced pero con coincidencia exacta.

await client.getCPAdvanced('Jalisco', { municipio: 'Guadalajara' });

Estados

getEstados()

Lista de todos los estados de México.

await client.getEstados();

getEstadoClave()

Estados con su clave oficial INEGI.

await client.getEstadoClave();

Municipios

getMunicipioPorEstado(estado)

Municipios de un estado.

await client.getMunicipioPorEstado('Jalisco');

getMunicipioClavePorEstado(estado)

Municipios con clave INEGI filtrados por nombre de estado.

await client.getMunicipioClavePorEstado('Jalisco');

getMunicipioClavePorClaveEstado(clave)

Municipios con clave INEGI filtrados por clave de estado.

await client.getMunicipioClavePorClaveEstado('14');

Colonias

getColoniaPorMunicipio(municipio)

Colonias de un municipio.

await client.getColoniaPorMunicipio('Guadalajara');

getColoniaPorEstadoMunicipio(estado, municipio)

Colonias con CP filtradas por estado y municipio.

await client.getColoniaPorEstadoMunicipio('Jalisco', 'Guadalajara');

Ciudades

getCitiesByStateCode(claveEstado)

Ciudades de un estado por su clave INEGI.

await client.getCitiesByStateCode('14');

Localidades

getLocalidadPorEstadoMunicipio(estado, municipio)

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

await client.getLocalidadPorEstadoMunicipio('Jalisco', 'Guadalajara');

getLocalidadPorClaveEstadoMunicipio(claveEstado, claveMunicipio)

Localidades filtradas por claves INEGI.

await client.getLocalidadPorClaveEstadoMunicipio('14', '039');

infoLocalidad(claveEstado, claveMunicipio, claveLocalidad)

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

await client.infoLocalidad('14', '039', '0001');

Vialidades

getVialidad(claveEstado, claveMunicipio, busqueda, limit, options?)

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

await client.getVialidad('14', '039', 'juarez', 10);
await client.getVialidad('14', '039', 'reforma', 5, { claveLocalidad: '0001' });

getTipoVialidad()

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

await client.getTipoVialidad();

Geocoding

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

infoCPGeocoding(cp, options?)

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

await client.infoCPGeocoding('06600');
await client.infoCPGeocoding('06600', { calle: 'Insurgentes', numero: '123' });

infoCPGeocodingReverse(lat, lng)

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

await client.infoCPGeocodingReverse(19.4326, -99.1332);

Cuenta

consultasDisponibles()

Saldo de créditos disponibles del token.

await client.consultasDisponibles();

ultimaActualizacionDB()

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

await client.ultimaActualizacionDB();

Ejemplo completo

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

npm install
npm run build
node example/example.mjs