README

copomex-php-client

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

• PHP 8.1+
• Sin dependencias externas (usa cURL nativo)
• PSR-4 autoloading
• Cubre los 24 endpoints disponibles

Instalación

composer require msweb/copomex-php-client

Inicio rápido

use Copomex\Copomex;

$client = new Copomex('TU_TOKEN');

$info = $client->infoCp('06600', simplified: true);
print_r($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

use Copomex\Copomex;
use Copomex\Exception\CopomexAPIException;
use Copomex\Exception\CopomexHTTPException;

$client = new Copomex('TU_TOKEN');

try {
    $result = $client->infoCp('99999');
} catch (CopomexAPIException $e) {
    echo "Error de API [{$e->apiCode}]: {$e->apiMessage}";
} catch (CopomexHTTPException $e) {
    echo "Error HTTP: {$e->statusCode}";
}

Clase	Cuándo se lanza
CopomexAPIException	La API devuelve error: true. Tiene ->apiCode y ->apiMessage.
CopomexHTTPException	Respuesta HTTP no exitosa (4xx, 5xx). Tiene ->statusCode.
CopomexException	Clase base de las dos anteriores.

Referencia de métodos

Constructor

new Copomex(string $token, int $timeout = 10)

Parámetro	Descripción
$token	Tu token de acceso. Usa 'pruebas' para desarrollo.
$timeout	Timeout de la petición en segundos (default: 10).

Códigos postales

infoCp(string $cp, bool $simplified = false): array

Información completa de un código postal.

Sin $simplified, devuelve un array de arrays (una entrada por colonia). Con true, devuelve un array con datos agregados.

$colonias = $client->infoCp('06600');                    // array[]
$info     = $client->infoCp('06600', simplified: true);  // array

searchCp(string $texto, ?int $limit = null): array

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

$client->searchCp('066');
$client->searchCp('066', limit: 10);

getColoniaPorCp(string $cp): array

Colonias asociadas a un código postal.

$client->getColoniaPorCp('06600');

getCpPorEstado(string $estado): array

Todos los códigos postales de un estado.

$client->getCpPorEstado('Jalisco');

getCpPorMunicipio(string $municipio): array

Códigos postales de un municipio.

$client->getCpPorMunicipio('Guadalajara');

searchCpAdvanced(string $estado, ?int $limit, ?string $municipio, ?string $colonia): array

Búsqueda avanzada de CPs con filtros opcionales (coincidencia parcial).

$client->searchCpAdvanced('Jalisco', municipio: 'Guadalajara', limit: 20);
$client->searchCpAdvanced('CDMX', colonia: 'Condesa');

getCpAdvanced(string $estado, ?int $limit, ?string $municipio, ?string $colonia): array

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

$client->getCpAdvanced('Jalisco', municipio: 'Guadalajara');

Estados

getEstados(): array

Lista de todos los estados de México.

$client->getEstados();

getEstadoClave(): array

Estados con su clave oficial INEGI.

$client->getEstadoClave();

Municipios

getMunicipioPorEstado(string $estado): array

Municipios de un estado.

$client->getMunicipioPorEstado('Jalisco');

getMunicipioClavePorEstado(string $estado): array

Municipios con clave INEGI, filtrados por nombre de estado.

$client->getMunicipioClavePorEstado('Jalisco');

getMunicipioClavePorClaveEstado(string $clave): array

Municipios con clave INEGI, filtrados por clave de estado.

$client->getMunicipioClavePorClaveEstado('14');

Colonias

getColoniaPorMunicipio(string $municipio): array

Colonias de un municipio.

$client->getColoniaPorMunicipio('Guadalajara');

getColoniaPorEstadoMunicipio(string $estado, string $municipio): array

Colonias con CP filtradas por estado y municipio.

$client->getColoniaPorEstadoMunicipio('Jalisco', 'Guadalajara');

Ciudades

getCitiesByStateCode(string $claveEstado): array

Ciudades de un estado por su clave INEGI.

$client->getCitiesByStateCode('14');

Localidades

getLocalidadPorEstadoMunicipio(string $estado, string $municipio): array

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

$client->getLocalidadPorEstadoMunicipio('Jalisco', 'Guadalajara');

getLocalidadPorClaveEstadoMunicipio(string $claveEstado, string $claveMunicipio): array

Localidades filtradas por claves INEGI de estado y municipio.

$client->getLocalidadPorClaveEstadoMunicipio('14', '039');

infoLocalidad(string $claveEstado, string $claveMunicipio, string $claveLocalidad): array

Información detallada de una localidad (incluye coordenadas y altitud).

$client->infoLocalidad('14', '039', '0001');

Vialidades

getVialidad(string $claveEstado, string $claveMunicipio, string $busqueda, int $limit, ?string $claveLocalidad): array

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

$client->getVialidad('14', '039', 'juarez', 10);
$client->getVialidad('14', '039', 'reforma', 5, '0001');

getTipoVialidad(): array

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

$client->getTipoVialidad();

Geocoding

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

infoCpGeocoding(string $cp, ?string $type, ?string $calle, ?string $numero): array

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

$client->infoCpGeocoding('06600');
$client->infoCpGeocoding('06600', calle: 'Insurgentes', numero: '123');

infoCpGeocodingReverse(float $lat, float $lng): array

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

$client->infoCpGeocodingReverse(19.4326, -99.1332);

Cuenta

consultasDisponibles(): array

Saldo de créditos disponibles del token.

$client->consultasDisponibles();

ultimaActualizacionDb(): array

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

$client->ultimaActualizacionDb();

Créditos

Consulta	Créditos
Todos los endpoints excepto geocoding	1
infoCpGeocoding	2
infoCpGeocodingReverse	2

Licencia

MIT — Multiservicios Web