Cliente PHP — copomex-php-client

Cliente oficial para PHP 8.1+. Usa cURL nativo, sin dependencias externas. PSR-4 autoloading, excepciones tipadas.

Paquete Packagist: packagist.org/packages/msweb/copomex-php-client

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

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

Constructor

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

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) {
    // La API respondió con error: true
    echo "Error de API [{$e->apiCode}]: {$e

Referencia de métodos

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 con filtros opcionales. Usa coincidencia parcial.

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

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

Igual que searchCpAdvanced pero con coincidencia exacta.

$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.

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

Ejemplo completo

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

composer install
php example/example.php