Resumen

Esta API proporciona acceso a la base de datos de códigos postales con información de más de 234,000 registros de 5 países.

🇲🇽

México

157,424

🇺🇸

USA

37,969

🇦🇷

Argentina

20,260

🇪🇸

España

14,664

🇨🇴

Colombia

3,681

Datos disponibles:

Códigos postales
Colonias/Localidades
Municipios y estados/departamentos/provincias
Coordenadas geográficas (CO, AR, ES)

Plan Gratuito:

1 API Key
1,000 consultas/hora
Todos los endpoints
Sin costo

Autenticación

Para usar la API necesitas una API Key. Regístrate gratis para obtener una.

Cómo obtener tu API Key:

Regístrate en /login
Se genera automáticamente tu API Key
Ve tu key en el Dashboard

Requisitos de Contraseña:

• Mínimo 8 caracteres
• Al menos una letra mayúscula (A-Z)
• Al menos una letra minúscula (a-z)
• Al menos un número (0-9)

Ejemplo válido: MiPassword123

Cómo usar tu API Key:

Opción 1: Header HTTP (recomendado)

X-API-Key: zp_tu_api_key_aqui

Opción 2: Query parameter

GET /api/zip/06600?api_key=zp_tu_api_key_aqui

Rate Limiting:

Los headers de respuesta incluyen información sobre tu límite:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 2024-01-15T11:00:00Z

Endpoints de Códigos Postales

Requieren API Key

Endpoints de Autenticación

Gestión de API Keys

Requieren JWT en header Authorization

Códigos de Respuesta

Código	Estado	Descripción
200	OK	Petición exitosa
201	Created	Recurso creado (registro, API Key)
400	Bad Request	Parámetros inválidos o faltantes
401	Unauthorized	API Key o token inválido/faltante
403	Forbidden	Cuenta desactivada o sin permisos
404	Not Found	Recurso no encontrado
429	Too Many Requests	Límite de consultas excedido
500	Server Error	Error interno del servidor

Ejemplos de Uso

JavaScript (fetch)

const API_KEY = 'zp_tu_api_key';

// Buscar código postal en México
const response = await fetch('https://api.codigos.zip/api/zip/06600?pais=MX', {
  headers: { 'X-API-Key': API_KEY }
});

// Buscar en Estados Unidos
const responseUS = await fetch('https://api.codigos.zip/api/zip/10001?pais=US', {
  headers: { 'X-API-Key': API_KEY }
});

// Buscar en España
const responseES = await fetch('https://api.codigos.zip/api/zip/28001?pais=ES', {
  headers: { 'X-API-Key': API_KEY }
});

cURL

# México
curl -H "X-API-Key: zp_tu_api_key" \
  "https://api.codigos.zip/api/zip/06600?pais=MX"

# Estados Unidos
curl -H "X-API-Key: zp_tu_api_key" \
  "https://api.codigos.zip/api/zip/10001?pais=US"

# España
curl -H "X-API-Key: zp_tu_api_key" \
  "https://api.codigos.zip/api/zip/28001?pais=ES"

# Listar países disponibles
curl -H "X-API-Key: zp_tu_api_key" \
  "https://api.codigos.zip/api/paises"

Python (requests)

import requests

API_KEY = 'zp_tu_api_key'
headers = {'X-API-Key': API_KEY}

# Buscar en México
response = requests.get(
    'https://api.codigos.zip/api/zip/06600',
    headers=headers,
    params={'pais': 'MX'}
)
print(response.json()['colonias'])

# Buscar en Colombia
response = requests.get(
    'https://api.codigos.zip/api/estados',
    headers=headers,
    params={'pais': 'CO'}
)
print(response.json()['estados'])

PHP

<?php
$apiKey = 'zp_tu_api_key';

// Buscar en Argentina
$ch = curl_init('https://api.codigos.zip/api/zip/1001?pais=AR');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

print_r($data['colonias']);