copomex-node-client

Cliente Node.js para la API de Copomex — consulta de códigos postales, colonias, municipios, estados, localidades, vialidades y geocoding de México.

• Node.js 18+ (usa fetch nativo — sin dependencias de producción)
• TypeScript con tipos incluidos
• Salida dual: ESM + CommonJS
• Cubre los 24 endpoints disponibles

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);

Puedes usar 'pruebas' como token para hacer pruebas sin costo ni registro. Los datos devueltos son aleatorios pero la estructura es real.

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) {
    console.error(`Error de API [${err.code}]: ${err.message}`);
  } else if (err instanceof CopomexHTTPError) {
    console.error(`Error HTTP: ${err.statusCode}`);
  }
}

| Clase | Cuándo se lanza | |---|---| | CopomexAPIError | La API devuelve error: true. Tiene .code y .message. | | CopomexHTTPError | Respuesta HTTP no exitosa (4xx, 5xx). Tiene .statusCode. | | CopomexError | Clase base de las dos anteriores. |

Referencia de métodos

Constructor

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

| Parámetro | Descripción | |---|---| | token | Tu token de acceso. Usa 'pruebas' para desarrollo. | | options.timeout | Timeout en milisegundos (default: 10000). |

Códigos postales

infoCP(cp, options?)

Información completa de un código postal.

Sin simplified, devuelve un array (una entrada por colonia del CP). 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 de CPs con filtros opcionales (coincidencia parcial).

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

getCPAdvanced(estado, options?)

Búsqueda exacta de CPs con filtros (coincidencias exactas, no parciales).

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 de estado y municipio.

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();

Créditos

| Consulta | Créditos | |---|---| | Todos los endpoints excepto geocoding | 1 | | infoCPGeocoding | 2 | | infoCPGeocodingReverse | 2 |

Licencia

MIT — Multiservicios Web