API REST de Códigos Postales de España
Integra en tiempo real la base de datos oficial de códigos postales, municipios, provincias y coordenadas GPS en tus aplicaciones web, ecommerce, ERPs o software móvil. Gratuita, sin registro y con cabeceras CORS activas.
Consola de Pruebas en Vivo (Sandbox)
Ejecuta consultas reales contra la API directamente desde tu navegador. Prueba con cualquier código postal de 5 dígitos, nombre de localidad o código de provincia:
{
"status": "success",
"total": 1,
"query": "28850",
"resultados": [
{
"codigo_postal": "28850",
"municipio": "Torrejón de Ardoz",
"provincia": "Madrid",
"codigo_ine": "28148000000",
"latitud": "40.4591561",
"longitud": "-3.4789902"
}
]
}
Documentación de Endpoints Oficiales
La API expone dos métodos principales a través del protocolo HTTPS estándar bajo el namespace /wp-json/cp/v1/:
1. Búsqueda por Código Postal o Municipio
Permite localizar poblaciones por su código de 5 cifras o buscar localidades por coincidencia de texto en el nombre:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
cp |
String (5 dígitos) | Opcional* | Código postal exacto a buscar (ej. 28850, 46001). |
q |
String | Opcional* | Término de búsqueda textual para municipios o poblaciones (ej. Torrejón, Alcalá). |
cp o q).
2. Listar Todos los Códigos Postales de una Provincia
Devuelve el listado íntegro de códigos postales y localidades pertenecientes a una provincia utilizando su código numérico INE de 2 dígitos:
| Parámetro en Ruta | Tipo | Ejemplo | Descripción |
|---|---|---|---|
{id} |
String (2 dígitos) | 28 (Madrid), 08 (Barcelona) |
Prefijo postal provincial oficial de 2 cifras (01 a 52). |
Ejemplos de Integración en tu Código
Copia y pega fácilmente el código de conexión en tu lenguaje o framework favorito:
// Consultar código postal con Fetch API moderno (Navegador o Node.js 18+)
async function buscarCodigoPostal(cp) {
try {
const url = `https://xn--cdigospostales-lob.es/wp-json/cp/v1/buscar?cp=${encodeURIComponent(cp)}`;
const response = await fetch(url);
if (!response.ok) {
throw new Error(`Error HTTP: ${response.status}`);
}
const data = await response.json();
console.log(`Encontrados ${data.total} resultados:`, data.resultados);
return data.resultados;
} catch (error) {
console.error('Fallo en la consulta de código postal:', error);
}
}
// Ejemplo de uso:
buscarCodigoPostal('28850').then(lugares => {
lugares.forEach(item => {
console.log(`${item.codigo_postal} → ${item.municipio} (${item.provincia}) [GPS: ${item.latitud}, ${item.longitud}]`);
});
});
# Consultar código postal con Python usando la librería 'requests'
import requests
def consultar_codigo_postal(cp):
endpoint = "https://xn--cdigospostales-lob.es/wp-json/cp/v1/buscar"
params = {"cp": cp}
response = requests.get(endpoint, params=params)
response.raise_for_status()
data = response.json()
print(f"Total registros: {data['total']}")
for item in data['resultados']:
print(f"{item['codigo_postal']} - {item['municipio']} ({item['provincia']})")
return data['resultados']
# Ejecutar consulta
if __name__ == "__main__":
consultar_codigo_postal("28850")
<?php
// Consultar código postal con PHP usando cURL
function consultar_cp($codigo_postal) {
$url = 'https://xn--cdigospostales-lob.es/wp-json/cp/v1/buscar?cp=' . urlencode($codigo_postal);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
$raw = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($http_code === 200 && $raw) {
$json = json_decode($raw, true);
return $json['resultados'] ?? [];
}
return [];
}
// Uso:
$resultados = consultar_cp('28850');
print_r($resultados);
?>
# Consulta directa desde la terminal o scripts bash
curl -X GET "https://xn--cdigospostales-lob.es/wp-json/cp/v1/buscar?cp=28850" \
-H "Accept: application/json"
# Listar todos los códigos de la provincia de Madrid (código 28)
curl -X GET "https://xn--cdigospostales-lob.es/wp-json/cp/v1/provincia/28" \
-H "Accept: application/json"
Preguntas Frecuentes sobre la API
¿Es necesario registrarse o pedir una API Key?
No. La API es totalmente abierta y de acceso público. No requiere registros, tokens Bearer ni claves de suscripción.
¿Puedo hacer peticiones desde una web frontend (CORS)?
Sí, los endpoints incluyen cabeceras Access-Control-Allow-Origin: * para que puedas llamarlos directamente desde Javascript en el navegador (React, Vue, Angular o vanilla JS).
¿Existen límites de peticiones (Rate Limiting)?
No hay restricciones artificiales para un uso razonable de consultas estándar. Si necesitas realizar millones de peticiones diarias o procesamiento offline, te recomendamos descargar el dataset en JSON o la base de datos SQL.
¿Con qué frecuencia se actualizan los datos?
La base de datos se mantiene sincronizada con las modificaciones que publica la Sociedad Estatal Correos y Telégrafos y el Instituto Nacional de Estadística (INE).