¡Novedad! Consulta el valor de referencia sin Cl@ve ni certificado. Gratis

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

De la referencia catastral al JSON: token, jobs y polling, callback, errores y ejemplos en curl, JavaScript, Python y PHP para la API del Catastro gratuita.

Equipo CatastroAPIActualizado el 7 min de lectura

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

  1. Rellena el formulario de solicitud con tu nombre o empresa, tu email y para qué vas a usar la API.
  2. Recibes un correo de confirmación. Revisamos cada solicitud a mano.
  3. 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.

CatastroAPI no es un servicio oficial. Los datos proceden de la Sede Electrónica del Catastro: los descriptivos son datos no protegidos y el valor de referencia tampoco es un dato protegido, según las preguntas frecuentes del Catastro. Lo que no ofrece la API son datos protegidos como el titular o el valor catastral.

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:

ValorQué devuelve
fullValor de referencia y datos descriptivos en una sola sesión (unos 5 s). La opción recomendada.
valorSolo el importe del valor de referencia y la dirección básica
descriptivaSolo los datos descriptivos: inmueble, parcela y construcciones
certificadoEl 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"
EstadoQué significa
waitingEsperando turno en la cola
activeSe está procesando ahora mismo
delayedProgramado para reintentar tras una espera
completedTerminado: los datos están en result
failedFalló 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ódigoCuándoQué hacer
400La 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.
401Falta la cabecera Authorization o el token no es válidoRevisa el formato Bearer <token>
403Tu cuenta no está activa o está suspendidaEscríbenos
404El job no existe o ha caducado (se guardan 24 horas)Crea un job nuevo
429Tu cuenta tiene un límite diario de consultas y lo has alcanzadoEspera al día siguiente
500Error inesperado del servidorReintenta 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.
¿Aún no tienes token? Solicita acceso gratis. Revisamos cada solicitud a mano y te lo enviamos por email.

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.

Todos estos datos, en una llamada a la API.Valor de referencia, datos descriptivos y certificado PDF. Gratis para siempre.
Solicitar acceso gratis