Si tu producto trabaja con inmuebles en España, tarde o temprano necesitarás datos del Catastro: el valor de referencia, la superficie, el año de construcción o el certificado oficial. Con CatastroAPI los obtienes en JSON a partir de una referencia catastral, gratis y en tres pasos: creas un job, esperas el resultado y lo guardas. Esta guía cubre el alta, el flujo asíncrono, los errores y ejemplos listos para copiar.
Qué necesitas para usar la API del Catastro
- Un token personal de CatastroAPI.
- La referencia catastral completa del inmueble: 20 caracteres alfanuméricos.
- Un backend en cualquier lenguaje que haga peticiones HTTP.
La URL base es https://api.catastroapi.com y todas las peticiones, salvo el health check GET /, llevan la cabecera Authorization: Bearer <tu token>.
Cómo conseguir tu token
- Rellena el formulario de solicitud con tu nombre o empresa, tu email y para qué vas a usar la API.
- Recibes un correo de confirmación. Revisamos cada solicitud a mano.
- Cuando la aprobamos, te enviamos por email tu token personal con un ejemplo de llamada.
Guárdalo como un secreto (una variable de entorno, por ejemplo) y no lo subas a tu repositorio.
Paso 1: crear un job con la referencia catastral
Las consultas al Catastro tardan unos segundos, así que la API funciona con una cola. Envías la referencia a POST /jobs y recibes un jobId al momento:
curl -X POST https://api.catastroapi.com/jobs \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"reference":"5163834XH7856S0292SX","includes":["full"]}'
# → 201 { "jobId": "42", "status": "pending", "reference": "...", "includes": ["full"], "callbackUrl": null }
El campo includes indica qué datos quieres:
| Valor | Qué devuelve |
|---|---|
full | Valor de referencia y datos descriptivos en una sola sesión (unos 5 s). La opción recomendada. |
valor | Solo el importe del valor de referencia y la dirección básica |
descriptiva | Solo los datos descriptivos: inmueble, parcela y construcciones |
certificado | El PDF oficial del Catastro, en base64 |
Se pueden combinar: ["full", "certificado"] trae todo y además el PDF. Si solo necesitas el valor de referencia, full sigue siendo la mejor opción, porque trae también la superficie y el año de construcción en la misma sesión.
Paso 2: recoger el resultado con polling o callback
Tienes dos formas de saber cuándo ha terminado el job. Puedes usar las dos a la vez.
Polling con GET /jobs/:jobId
Consulta el job cada 10–15 segundos hasta que su status sea completed o failed. De media tarda entre 5 y 10 segundos. No bajes de 5 segundos entre consultas: no lo acelera.
curl https://api.catastroapi.com/jobs/42 \
-H "Authorization: Bearer $TOKEN"
| Estado | Qué significa |
|---|---|
waiting | Esperando turno en la cola |
active | Se está procesando ahora mismo |
delayed | Programado para reintentar tras una espera |
completed | Terminado: los datos están en result |
failed | Falló tras reintentar; el motivo está en error |
Callback a tu servidor
Si añades callbackUrl al crear el job (debe empezar por http:// o https://), al terminar te enviamos un POST con el resultado. Tu servidor debe responder con cualquier código 2xx en menos de 15 segundos. Solo hay un intento: si tu servidor está caído en ese momento, no se reintenta. Por eso conviene mantener el polling como respaldo; el resultado sigue disponible en GET /jobs/:jobId durante 24 horas.
Paso 3: leer los datos del inmueble
Con includes: ["full"], los datos están en result.full.data. Este es un extracto:
{
"valor": {
"valorReferencia": 79883.22,
"fechaValor": "30/12/2025",
"direccion": "CL ALCALDE LUIS PASCUAL 8 Es:1 Pl:01 Pt:D",
"codigoPostal": "02660",
"municipio": "CAUDETE",
"clase": "Urbano",
"usoPrincipal": "Residencial"
},
"descriptiva": {
"inmueble": { "superficieConstruida": 132, "anioConstruccion": 2011 },
"parcela": { "superficieGrafica": 1439, "participacion": 2 },
"construcciones": [
{ "usoPrincipal": "VIVIENDA", "planta": "01", "puerta": "D", "superficie": 113 }
]
},
"descriptivaError": null
}
Si pides varios includes, result tiene una entrada por cada uno (result.full, result.certificado…), y cada entrada tiene la forma { data, error }. Un fallo en una pieza no tumba el job entero: puedes recibir los datos y no el PDF, o al revés. Con full, si el valor llega pero la descriptiva falla, verás descriptiva: null y el motivo en descriptivaError.
Ejemplos completos en JavaScript, Python y PHP
JavaScript (Node.js)
const API = 'https://api.catastroapi.com';
const headers = { Authorization: `Bearer ${process.env.CATASTRO_TOKEN}`, 'Content-Type': 'application/json' };
async function datosCatastro(rc) {
const r = await fetch(`${API}/jobs`, {
method: 'POST', headers,
body: JSON.stringify({ reference: rc, includes: ['full'] }),
});
if (!r.ok) throw new Error(`POST /jobs HTTP ${r.status}`);
const { jobId } = await r.json();
const inicio = Date.now();
while (Date.now() - inicio < 10 * 60 * 1000) {
await new Promise((ok) => setTimeout(ok, 10000));
const job = await (await fetch(`${API}/jobs/${jobId}`, { headers })).json();
if (job.status === 'completed') {
const { data, error } = job.result.full;
if (error) throw new Error(error);
return data;
}
if (job.status === 'failed') throw new Error(job.error);
}
throw new Error('Tiempo de espera agotado');
}
Python
import os, time, requests
API = "https://api.catastroapi.com"
H = {"Authorization": f"Bearer {os.environ['CATASTRO_TOKEN']}"}
def datos_catastro(rc):
r = requests.post(f"{API}/jobs", headers=H, json={"reference": rc, "includes": ["full"]})
r.raise_for_status()
job_id = r.json()["jobId"]
for _ in range(60):
time.sleep(10)
job = requests.get(f"{API}/jobs/{job_id}", headers=H).json()
if job["status"] == "completed":
pieza = job["result"]["full"]
if pieza["error"]:
raise RuntimeError(pieza["error"])
return pieza["data"]
if job["status"] == "failed":
raise RuntimeError(job["error"])
raise TimeoutError("El job no terminó a tiempo")
PHP
$api = 'https://api.catastroapi.com';
$h = "Authorization: Bearer " . getenv('CATASTRO_TOKEN') . "\r\nContent-Type: application/json";
$job = json_decode(file_get_contents("$api/jobs", false, stream_context_create(['http' => [
'method' => 'POST', 'header' => $h,
'content' => json_encode(['reference' => '5163834XH7856S0292SX', 'includes' => ['full']]),
]])), true);
do {
sleep(10);
$r = json_decode(file_get_contents("$api/jobs/{$job['jobId']}", false,
stream_context_create(['http' => ['header' => $h]])), true);
} while (in_array($r['status'], ['waiting', 'active', 'delayed']));
if ($r['status'] !== 'completed' || $r['result']['full']['error']) {
throw new RuntimeException($r['error'] ?? $r['result']['full']['error']);
}
$datos = $r['result']['full']['data'];
Errores de la API y cómo tratarlos
| Código | Cuándo | Qué hacer |
|---|---|---|
400 | La referencia no tiene 20 caracteres alfanuméricos, includes está vacío o tiene valores no válidos, o la callbackUrl no empieza por http(s) | Corrige la petición. No se ha consultado el Catastro. |
401 | Falta la cabecera Authorization o el token no es válido | Revisa el formato Bearer <token> |
403 | Tu cuenta no está activa o está suspendida | Escríbenos |
404 | El job no existe o ha caducado (se guardan 24 horas) | Crea un job nuevo |
429 | Tu cuenta tiene un límite diario de consultas y lo has alcanzado | Espera al día siguiente |
500 | Error inesperado del servidor | Reintenta más tarde y avísanos si se repite |
Los errores del propio Catastro, como una referencia que no existe, no son errores HTTP: el job termina con status: "completed" y el motivo está en result.<pieza>.error. Compruébalo siempre antes de leer data.
Buenas prácticas: límites, caché y seguridad
- No te preocupes por la concurrencia. La cola la gestiona el servidor: procesa varios jobs en paralelo y respeta un ritmo máximo por minuto. Si encolas muchos a la vez, simplemente tardarán algo más.
- Guarda los resultados en tu base de datos en cuanto los recibas, junto con
fechaValor. El valor de referencia se determina por años, así que no tiene sentido repetir la consulta cada vez que alguien abre la ficha del inmueble. - Llama desde tu backend, nunca desde el navegador: tu token quedaría a la vista.
- Usa la cola en producción. Existen endpoints síncronos (
GET /reference/:reference/full,/descriptiva,/certificado) para scripts o herramientas internas, pero cada llamada abre un navegador en el servidor y Cloudflare corta las peticiones que pasan de 100 segundos. - Valida la referencia antes de enviarla: 20 caracteres, sin espacios ni guiones. Te ahorras un 400.
Preguntas frecuentes
¿Hay una API oficial del Catastro?
El Catastro ofrece servicios web públicos con datos no protegidos, como la superficie o el uso. El valor de referencia se consulta en la Sede Electrónica, con identificación. CatastroAPI reúne esos datos en una sola llamada, pero no es un servicio oficial del Catastro.
¿Cuánto cuesta CatastroAPI?
Nada. Es gratuita para siempre, sin tarjeta y sin planes de pago. Solo tienes que solicitar acceso y esperar a que revisemos tu solicitud.
¿Cuánto tarda una consulta?
De media entre 5 y 10 segundos por job. Si la cola tiene mucha carga puede tardar algo más, por eso la API funciona con jobs asíncronos.
¿Puedo llamar a la API desde el navegador?
No es recomendable: el token quedaría expuesto. Llama siempre desde tu backend y guarda los resultados en tu base de datos.