PHPackages                             msweb/copomex-php-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. msweb/copomex-php-client

ActiveLibrary[API Development](/categories/api)

msweb/copomex-php-client
========================

Cliente PHP para la API de Copomex — códigos postales de México

00PHP

Pushed todayCompare

[ Source](https://github.com/EdsonBurgosMsWeb/copomex-php-client)[ Packagist](https://packagist.org/packages/msweb/copomex-php-client)[ RSS](/packages/msweb-copomex-php-client/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersionsUsed By (0)

 [![Copomex](assets/logo.png)](assets/logo.png)

copomex-php-client
==================

[](#copomex-php-client)

Cliente PHP para la [API de Copomex](https://copomex.com) — 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
-----------

[](#instalación)

```
composer require msweb/copomex-php-client
```

---

Inicio rápido
-------------

[](#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
-----------------

[](#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}";
}
```

ClaseCuá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
---------------------

[](#referencia-de-métodos)

### Constructor

[](#constructor)

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

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

### Códigos postales

[](#códigos-postales)

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

[](#infocpstring-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`

[](#searchcpstring-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`

[](#getcoloniaporcpstring-cp-array)

Colonias asociadas a un código postal.

```
$client->getColoniaPorCp('06600');
```

#### `getCpPorEstado(string $estado): array`

[](#getcpporestadostring-estado-array)

Todos los códigos postales de un estado.

```
$client->getCpPorEstado('Jalisco');
```

#### `getCpPorMunicipio(string $municipio): array`

[](#getcppormunicipiostring-municipio-array)

Códigos postales de un municipio.

```
$client->getCpPorMunicipio('Guadalajara');
```

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

[](#searchcpadvancedstring-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`

[](#getcpadvancedstring-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

[](#estados)

#### `getEstados(): array`

[](#getestados-array)

Lista de todos los estados de México.

```
$client->getEstados();
```

#### `getEstadoClave(): array`

[](#getestadoclave-array)

Estados con su clave oficial INEGI.

```
$client->getEstadoClave();
```

---

### Municipios

[](#municipios)

#### `getMunicipioPorEstado(string $estado): array`

[](#getmunicipioporestadostring-estado-array)

Municipios de un estado.

```
$client->getMunicipioPorEstado('Jalisco');
```

#### `getMunicipioClavePorEstado(string $estado): array`

[](#getmunicipioclaveporestadostring-estado-array)

Municipios con clave INEGI, filtrados por nombre de estado.

```
$client->getMunicipioClavePorEstado('Jalisco');
```

#### `getMunicipioClavePorClaveEstado(string $clave): array`

[](#getmunicipioclaveporclaveestadostring-clave-array)

Municipios con clave INEGI, filtrados por clave de estado.

```
$client->getMunicipioClavePorClaveEstado('14');
```

---

### Colonias

[](#colonias)

#### `getColoniaPorMunicipio(string $municipio): array`

[](#getcoloniapormunicipiostring-municipio-array)

Colonias de un municipio.

```
$client->getColoniaPorMunicipio('Guadalajara');
```

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

[](#getcoloniaporestadomunicipiostring-estado-string-municipio-array)

Colonias con CP filtradas por estado y municipio.

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

---

### Ciudades

[](#ciudades)

#### `getCitiesByStateCode(string $claveEstado): array`

[](#getcitiesbystatecodestring-claveestado-array)

Ciudades de un estado por su clave INEGI.

```
$client->getCitiesByStateCode('14');
```

---

### Localidades

[](#localidades)

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

[](#getlocalidadporestadomunicipiostring-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`

[](#getlocalidadporclaveestadomunicipiostring-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`

[](#infolocalidadstring-claveestado-string-clavemunicipio-string-clavelocalidad-array)

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

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

---

### Vialidades

[](#vialidades)

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

[](#getvialidadstring-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`

[](#gettipovialidad-array)

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

```
$client->getTipoVialidad();
```

---

### Geocoding

[](#geocoding)

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

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

[](#infocpgeocodingstring-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`

[](#infocpgeocodingreversefloat-lat-float-lng-array)

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

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

---

### Cuenta

[](#cuenta)

#### `consultasDisponibles(): array`

[](#consultasdisponibles-array)

Saldo de créditos disponibles del token.

```
$client->consultasDisponibles();
```

#### `ultimaActualizacionDb(): array`

[](#ultimaactualizaciondb-array)

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

```
$client->ultimaActualizacionDb();
```

---

Créditos
--------

[](#créditos)

ConsultaCréditosTodos los endpoints excepto geocoding1`infoCpGeocoding`2`infoCpGeocodingReverse`2---

Licencia
--------

[](#licencia)

MIT — [Multiservicios Web](https://multiservicios-web.com.mx)

###  Health Score

20

↑

LowBetter than 13% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity8

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cbddbd611ddb8c439c8b983a1090b581e6581a6df545b49249329f5531451c5f?d=identicon)[EdsonBurgosMsWeb](/maintainers/EdsonBurgosMsWeb)

---

Top Contributors

[![EdsonBurgosMsWeb](https://avatars.githubusercontent.com/u/165206070?v=4)](https://github.com/EdsonBurgosMsWeb "EdsonBurgosMsWeb (1 commits)")

### Embed Badge

![Health badge](/badges/msweb-copomex-php-client/health.svg)

```
[![Health](https://phpackages.com/badges/msweb-copomex-php-client/health.svg)](https://phpackages.com/packages/msweb-copomex-php-client)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M19](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k12](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)