# Catastro España — inmuebles por referencia catastral (`daniizarsan/catastro-espana`) Actor

Consulta oficial de la Sede Electrónica del Catastro: cualquier inmueble de España por referencia catastral o dirección completa. Uso, superficie construida, coeficiente de participación, año de construcción y desglose de construcciones por planta. Fuente oficial gratuita.

- **URL**: https://apify.com/daniizarsan/catastro-espana.md
- **Developed by:** [Daniel de la Zarza Sánchez](https://apify.com/daniizarsan) (community)
- **Categories:** Real estate
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Catastro España — inmuebles por referencia catastral o dirección

Consulta oficial de la **Sede Electrónica del Catastro** (servicios OVC, datos abiertos sin clave):
cualquier inmueble de España, con su **uso, superficie construida, coeficiente de participación,
año de construcción, escalera/planta/puerta, código postal y desglose de construcciones por planta**.

Familia **España — datos oficiales**: `bdns-subsidios` (subvenciones) · `borme-espana` (Registro Mercantil) · `catastro-espana` (inmuebles).

### Qué devuelve (una referencia catastral = una fila)

Ejemplo real (CL GLORIA 51, Santa Cruz de Mudela):

```json
{
  "id": "9872023VH5797S0001WX",
  "referenciaCatastral": "9872023VH5797S0001WX",
  "tipoBien": "urbano",
  "direccion": "CL GLORIA 51 13730 SANTA CRUZ DE MUDELA (CIUDAD REAL)",
  "tipoVia": "CL",
  "nombreVia": "GLORIA",
  "numero": "51",
  "codigoPostal": "13730",
  "municipio": "SANTA CRUZ DE MUDELA",
  "provincia": "CIUDAD REAL",
  "uso": "Residencial",
  "superficie": 308,
  "coeficiente": 100.0,
  "antiguedad": 1980,
  "construcciones": [
    { "destino": "VIVIENDA", "planta": "00", "puerta": "01", "superficie": 109 },
    { "destino": "ALMACEN", "planta": "00", "puerta": "02", "superficie": 187 },
    { "destino": "OTROS USOS", "planta": "00", "puerta": "03", "superficie": 12 }
  ],
  "numConstrucciones": 3,
  "superficieConstruida": 308,
  "fechaConsulta": "2026-11-04"
}
```

### Dos modos de uso

1. **Referencias catastrales** — pega una o varias RC (14 o 20 caracteres, con o sin espacios,
   mayúsculas/minúsculas da igual):
   `referenciasCatastrales: "9872023VH5797S, 0545206VK4704F"`
2. **Búsqueda por dirección** — provincia + municipio + tipo de vía + vía + portal:
   `provincia: "Coruña", municipio: "Santiago de Compostela", tipoVia: "CL", via: "Praterias", numero: "3"`
   (sin acentos da igual; la provincia se resuelve contra la lista oficial del Catastro).

### Reglas del actor

- **Esquema base duro**: si la fuente devuelve una fila sin los campos base, el run aborta sin guardar basura.
- **Detalle tolerante**: si el DNP de una referencia falla, esa fila sale solo con la referencia y el
  contexto de búsqueda — nunca campos de error, nunca se pierde la fila.
- **Anti-duplicados**: una referencia = una fila; si la parcela tiene varios bienes, una fila por bien
  con su RC completa de 20 caracteres (la fuente los lista en `lrcdnp` y el actor consulta cada uno).
- **Contexto tolerante**: si la referencia no corresponde a la provincia/municipio indicados, el actor
  reintenta solo con la RC (única a nivel nacional) y conserva el detalle.
- **Filtros validados al inicio**: provincia/municipio/vía que no existen abortan el run con un
  mensaje claro antes de emitir nada.
- **Checkpoint**: si el run se interrumpe, la siguiente ejecución con los mismos filtros reanuda
  desde la última referencia procesada.

### Casos de uso

- **Proptech y tasación**: ficha rápida de cada inmueble de un portal (superficies, usos, antigüedad).
- **Cruce con BORME** (`borme-espana`): sociedades constituidas → domicilio → inmueble del Catastro.
- **Estudios de mercado**: inventario de usos y superficies de una dirección completa.
- **Operadores de activos**: desglose de construcciones por planta y destino (VIVIENDA, ALMACEN, OFICINA...).

### Filtros que valida al inicio

| Filtro | Comprobación |
|---|---|
| `referenciasCatastrales` | Formato 14/20 caracteres; máx. 5.000 por ejecución |
| `provincia` | Debe existir en la lista oficial (¡"A CORUÑA", no "LA CORUÑA"!) |
| `municipio` | Debe existir en la provincia |
| `tipoVia` | Sigla oficial (CL, AV, PS, PZ, CM...) |
| `via` + `numero` | Deben existir; la fuente no lista calles enteras |

### Precio

Pay-per-event: **$0,003 por inmueble** (evento por item del dataset). El cómputo del actor lo paga quien lo ejecuta. Efectivo desde el 19-nov-2026 (periodo de aviso de Apify); hasta entonces la ficha muestra "Free".

### Fuente y frecuencia

Servicios OVC de la Sede Electrónica del Catastro (oficial, gratuito, sin clave). Consulta
en vivo en cada ejecución: no hay caché entre ejecuciones. Ver detalle en [FUENTE-CATASTRO.md](FUENTE-CATASTRO.md).

### Otros actores de la familia

- **Subvenciones BDNS (España)** — convocatorias oficiales con cruces BOE y concesiones:
  `apify/bdns-subsidios`
- **BORME España** — nuevas sociedades, disoluciones y cargos del Registro Mercantil:
  `apify/borme-espana`
- **Subastas España** — subastas del BOE con valores, lotes y cruce Catastro directo:
  `apify/subastas-espana`

# Actor input Schema

## `referenciasCatastrales` (type: `string`):

14 o 20 caracteres, con o sin espacios, mayusculas da igual. Tiene prioridad sobre la busqueda por direccion.

## `provincia` (type: `string`):

Nombre oficial o casi: "A Coruna", "Coruna", "Girona"... Sin acentos da igual.

## `municipio` (type: `string`):

p. ej. "Madrid" o "Santa Cruz de Mudela". Sin acentos da igual.

## `tipoVia` (type: `string`):

CL (calle), AV (avenida), PS (paseo), PZ (plaza), CM (camino), JR (jardin), GD (gran via/vertical), PT (poligono), CR (carretera), AC (acceso), RJ (rambla), CG (coleccion), ES (escalera), TR (travesia), CO (colectivo), OP (obra paso), SL (salon), PL (poligono industrial).

## `via` (type: `string`):

p. ej. "Alcala" o "Gloria". Sin acentos da igual.

## `numero` (type: `string`):

p. ej. "1". La fuente exige portal: no hay listado de la calle entera.

## `maxItems` (type: `integer`):

Un portal tipico trae 1-30 inmuebles (uno por piso).

## `continuarDespues` (type: `boolean`):

Checkpoint por bloque: si el run se cae, la siguiente ejecucion con los mismos filtros reanuda.

## Actor input object example

```json
{
  "maxItems": 200,
  "continuarDespues": true
}
```

# Actor output Schema

## `inmuebles` (type: `string`):

Dataset de bienes inmuebles: id, referenciaCatastral, provincia, municipio, via, numero, uso, superficie, coeficiente, anio (AAAA-MM-DD), escalera/planta/puerta, codigoPostal y construccionesPorPlanta.

## `resumen` (type: `string`):

Contadores: referencias resueltas, bienes emitidos, fallos de cruce y presupuesto de peticiones.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("daniizarsan/catastro-espana").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("daniizarsan/catastro-espana").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call daniizarsan/catastro-espana --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,daniizarsan/catastro-espana"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/adcq9FX3RDf3CfgG5/builds/1VOUaEQvNtf9oeo1X/openapi.json