# Predio — API de datos catastrales de España para agentes de IA

> Predio (prediohq.com) es una API de pago por uso que devuelve en JSON estructurado los datos catastrales no protegidos de inmuebles españoles. Entrada: una referencia catastral (14/18/20 caracteres), unas coordenadas (lat/lon) o una dirección (provincia/municipio/vía/número). Salida: clase urbano/rústico, uso, superficie construida en m², año de construcción, dirección normalizada y desglose de construcciones o cultivos. Diseñada para ser invocada por agentes autónomos a mitad de tarea.

## Capacidad

- Función: dado un `referenciaCatastral`, unas coordenadas (lat/lon) o una dirección, devuelve los datos catastrales no protegidos del inmueble.
- Dominio: territorio común de España (excluye País Vasco y Navarra, con catastro foral propio).
- Determinismo: misma referencia -> misma respuesta estructurada. Sin captchas, sin login humano, sin HTML.
- Fuente de los datos: Dirección General del Catastro (organismo público), reutilizados conforme a su licencia de reutilización. Predio es un redistribuidor, no la fuente, y no es un servicio oficial.

## Endpoints

- Base de la API: https://api.prediohq.com
- MCP (recomendado): `POST /mcp` — JSON-RPC 2.0, Model Context Protocol (Streamable HTTP). Herramientas: `consultar_inmueble_catastro` (por referencia), `consultar_inmueble_por_coordenadas` (por lat/lon) y `consultar_inmueble_por_direccion` (por provincia/municipio/vía/número).
- REST (espejo), por referencia: `GET /v1/inmueble/{referenciaCatastral}` y `POST /v1/inmueble` con cuerpo `{ "referenciaCatastral": "..." }`.
- REST (espejo), por coordenadas: `GET /v1/inmueble/by-coords?lat={lat}&lon={lon}&srs={epsg}` y `POST /v1/inmueble/by-coords` con cuerpo `{ "lat": ..., "lon": ..., "srs": "EPSG:4326" }`.
- REST (espejo), por dirección: `GET /v1/inmueble/by-address?province={prov}&municipality={mun}&streetType={sigla}&streetName={via}&streetNumber={num}` y `POST /v1/inmueble/by-address` con cuerpo `{ "province": "...", "municipality": "...", "streetType": "CL", "streetName": "...", "streetNumber": "..." }`.
- Salud: `GET /health`.

## Descubrimiento

- Este archivo: https://prediohq.com/llms.txt
- Spec OpenAPI del REST /v1: https://prediohq.com/openapi.yaml
- Precios legibles por máquina: https://prediohq.com/pricing.json
- Precios (humanos): https://prediohq.com/pricing

## Entrada

- Por referencia — `referenciaCatastral` (string, obligatorio): 14, 18 o 20 caracteres alfanuméricos.
  - 20 caracteres: identifica un inmueble concreto. Ejemplo: `9872023VH5797S0001WX`.
  - 14 caracteres: identifica una parcela; si contiene varios inmuebles, la respuesta es una lista de candidatos.
- Por coordenadas — `lat` y `lon` (number, obligatorios) en grados decimales, y `srs` (string, opcional) con el código EPSG.
  - `srs` soportados (geográficos): `EPSG:4326` (WGS84, por defecto) y `EPSG:4258` (ETRS89). Ejemplo: `lat=41.3915&lon=2.1620`.
  - Resuelve la parcela que contiene el punto; si tiene varios inmuebles, devuelve la lista de candidatos. Misma salida que por referencia.
- Por dirección — `province`, `municipality`, `streetName`, `streetNumber` (string, obligatorios) y `streetType`, `block`, `stairway`, `floor`, `door` (string, opcionales).
  - Provincia y municipio van por NOMBRE en mayúsculas (no por código); `streetType` es la sigla de la vía (`CL`, `AV`, `PZ`...) y se recomienda para acertar. Ejemplo: `province=CIUDAD REAL&municipality=SANTA CRUZ DE MUDELA&streetType=CL&streetName=GLORIA&streetNumber=51`.
  - Solo direcciones urbanas. Si el número corresponde a varios inmuebles (propiedad horizontal), devuelve la lista de candidatos (afina con bloque/escalera/planta/puerta). Misma salida que por referencia.

## Salida (campos)

- `status`: `ok` (un inmueble) | `multiple` (lista de candidatos, HTTP 300).
- `property.class`: `urban` | `rustic`.
- `property.use`: uso principal (p. ej. Residencial, Agrario, Industrial).
- `property.builtAreaM2`: superficie construida total en m² (0 o null en rústico sin construcción).
- `property.yearBuilt`: año de construcción (null en rústico).
- `property.address`: domicilio normalizado (provincia, municipio, vía/número o polígono/parcela, código postal).
- `property.constructions[]`: desglose por local (uso, planta, puerta, m²) en urbano.
- `property.cultivations[]`: desglose por subparcela (cultivo, intensidad, m²) en rústico.
- `source`: proveedor, referencia y timestamp; flags `cached` y `stale`.

## Errores (contrato estable)

- `404 NOT_FOUND`: el inmueble no existe (o, por coordenadas, el punto no cae en ninguna parcela).
- `422 INVALID_REFERENCE`: referencia mal formada o con dígitos de control inválidos.
- `422 INVALID_COORDINATES`: SRS no soportado, o lat/lon ausentes o fuera de rango.
- `422 INVALID_ADDRESS`: falta provincia/municipio/vía/número, o la provincia/municipio/vía no existe.
- `402 PAYMENT_REQUIRED`: créditos agotados.
- `401 MISSING_API_KEY` / `INVALID_API_KEY`: falta o es desconocida la cabecera `x-api-key`.
- `429 RATE_LIMITED`: límite de peticiones superado.
- `502 CATASTRO_UNAVAILABLE`: la fuente de datos no respondió o devolvió un error de infraestructura.
- Los errores siempre se devuelven como JSON `{ "error": { "code", "message" } }`, nunca como XML ni con status ambiguo.

## Autenticación

- Cabecera `x-api-key` en cada petición. Sin login interactivo.
- La key debe estar emitida para un tenant; una key ausente o desconocida responde `401`.

## Precios

- Modelo: pago por llamada (usage-based). Cada consulta exitosa consume 1 crédito; saldo ACID por tenant.
- Free-tier: 250 créditos/mes para diagnóstico/sandbox antes de conectar la billetera de producción.
- Cabeceras por respuesta: `X-Credit-Cost` y `X-Credits-Remaining`. Reintentos idempotentes con `Idempotency-Key`.
- Pago: packs de créditos prepago vía Stripe (checkout). Coinbase X402 (micropago en stablecoin) como fast-follow.
- Las consultas que devuelven error de negocio (404/422) no consumen crédito. Cache hits y serve-stale sí cobran.

## Límites y políticas

- Solo lectura. No modifica datos del Catastro.
- Datos "no protegidos" (públicos) del Catastro; no incluye titularidad ni datos personales.
- Atribución: Dirección General del Catastro. Servicio no oficial, sin garantía de exactitud (la fuente de verdad es el Catastro).
- Reintento recomendado con backoff ante 502.

## Guías (contexto útil, legible por humanos y agentes)

- Afecciones de una parcela con los visores oficiales (SNCZI, Red Natura, costas, vías pecuarias): https://prediohq.com/guias/afecciones-parcela-referencia-catastral/
- Cómo consumir la API oficial de la OVC (SOAP) y sus comportamientos reales: https://prediohq.com/guias/consumir-api-catastro-soap-json/
- Comparativa de opciones de API del Catastro español (incluye cuándo NO usar Predio): https://prediohq.com/guias/api-catastro-comparativa/

## Próximamente: ParcelGuard (early access, aún sin API pública)

- Qué será: dada una referencia catastral, un JSON de AFECCIONES de la parcela — inundabilidad (SNCZI, T10/T100/T500), Red Natura 2000 (LIC/ZEC y ZEPA), servidumbre de costas (DPMT) y vías pecuarias — intersectando la geometría oficial (WFS INSPIRE de la DGC) con las capas públicas del MITECO/IDEE. Fuente y fecha citadas por capa. Pre-screening informativo: no sustituye certificaciones oficiales.
- Estado: early access con waitlist. NO expone endpoints todavía; no intentes llamarlo.
- Informe de muestra con una parcela real: https://prediohq.com/parcelguard/ejemplo
- Waitlist (para humanos): https://prediohq.com/parcelguard/
- Pago previsto por informe (no por llamada), con batch y API.