Cómo obtener datos del Catastro por API: guía con ejemplos

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. Esta guía explica cómo obtenerlos en JSON con CatastroAPI, gratis y en tres pasos.

Qué necesitas

• Un token de CatastroAPI. Se solicita gratis desde la portada y te llega por email cuando aprobamos la cuenta.
• La referencia catastral completa del inmueble: 20 caracteres alfanuméricos.
• Cualquier lenguaje que haga peticiones HTTP.

La URL base es https://api.catastroapi.com y todas las peticiones llevan la cabecera Authorization: Bearer <tu token>.

Paso 1: crear un job

Las consultas al Catastro tardan unos segundos, así que la API funciona con una cola. Envías la referencia 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"]}'

# → { "jobId": "42", "status": "pending", ... }

El campo includes indica qué datos quieres:

Se pueden combinar: ["full", "certificado"] trae todo y además el PDF.

Paso 2: recoger el resultado

Consulta el job cada 10–15 segundos hasta que su status sea completed o failed. De media tarda entre 5 y 10 segundos:

curl https://api.catastroapi.com/jobs/42 \
  -H "Authorization: Bearer $TOKEN"

Si prefieres no hacer polling, añade una callbackUrl al crear el job y te enviaremos el resultado con un POST cuando termine. Recomendamos mantener el polling como respaldo, por si tu servidor no está disponible en ese momento.

Paso 3: usar los datos

Con includes: ["full"], los datos están en result.full.data:

{
  "valor": {
    "valorReferencia": 79883.22,
    "fechaValor": "30/12/2025",
    "direccion": "CL ALCALDE LUIS PASCUAL 8 Es:1 Pl:01 Pt:D",
    "codigoPostal": "02660",
    "municipio": "CAUDETE",
    "usoPrincipal": "Residencial"
  },
  "descriptiva": {
    "inmueble": { "superficieConstruida": 132, "anioConstruccion": 2011 },
    "parcela": { "superficieGrafica": 1439, "participacion": 2 },
    "construcciones": [
      { "usoPrincipal": "VIVIENDA", "planta": "01", "puerta": "D", "superficie": 113 }
    ]
  }
}

Ejemplos completos

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 { jobId } = await (await fetch(`${API}/jobs`, {
    method: 'POST', headers,
    body: JSON.stringify({ reference: rc, includes: ['full'] }),
  })).json();

  for (;;) {
    await new Promise((r) => setTimeout(r, 10000));
    const job = await (await fetch(`${API}/jobs/${jobId}`, { headers })).json();
    if (job.status === 'completed') return job.result.full.data;
    if (job.status === 'failed') throw new Error(job.error);
  }
}

Python

import os, time, requests

API = "https://api.catastroapi.com"
H = {"Authorization": f"Bearer {os.environ['CATASTRO_TOKEN']}"}

def datos_catastro(rc):
    job_id = requests.post(f"{API}/jobs", headers=H,
                           json={"reference": rc, "includes": ["full"]}).json()["jobId"]
    while True:
        time.sleep(10)
        job = requests.get(f"{API}/jobs/{job_id}", headers=H).json()
        if job["status"] == "completed":
            return job["result"]["full"]["data"]
        if job["status"] == "failed":
            raise RuntimeError(job["error"])

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

$datos = $r['result']['full']['data'];

Errores y buenas prácticas

• 400: la referencia no tiene 20 caracteres alfanuméricos o includes no es válido. No se consulta el Catastro.
• 401 / 403: falta el token, no es correcto o la cuenta no está activa.
• 404 en /jobs/:id: el job no existe o ha caducado. Los resultados se guardan 24 horas.
• Los errores del propio Catastro, como una referencia que no existe, llegan dentro del job: status será completed y el motivo estará en result.<parte>.error. Compruébalo siempre antes de leer data.
• Guarda los resultados en tu base de datos. El valor de referencia de un año no cambia, así que no hace falta repetir la consulta.
• Llama desde tu backend, nunca desde el navegador: tu token quedaría a la vista.

Preguntas frecuentes