# 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) o unas coordenadas (lat/lon). 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` o unas coordenadas (lat/lon), 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.
- Próximamente: consulta por dirección (calle/número).

## 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) y `consultar_inmueble_por_coordenadas` (por lat/lon).
- 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" }`.
- 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.

## 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.
- `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.