Brains API v2

Empezar

Toda llamada lleva tu clave en la cabecera Authorization. Se admite tal cual o con el prefijo Bearer; las dos formas valen.

curl -H "Authorization: TU_CLAVE" /api/cuenta/yo

La base de esta instalación es . También tienes Swagger para probar desde el navegador.

Cómo se pide un dato español

Mercado y comparables parten siempre de un punto, y solo de uno. Se manda exactamente uno de estos tres, por este orden de fiabilidad:

Campo	Qué es
referenciaCatastral	La más fiable: identifica una parcela. Se resuelve contra catastro; si mandas la de 20 caracteres se recorta a los 14 de la parcela.
latitud + longitud	Un punto exacto, sin garantía de que sea el inmueble. Las dos juntas o ninguna.
direccion	Se geocodifica con Google acotando por pais. Admite municipio y codigoPostal para afinar.

Mandar los tres vacíos, o más de uno a la vez, es un 400. Con el punto resuelto se saca el OBJECTID del nivel pedido, que es la única clave con la que se cruzan las estadísticas. Toda respuesta incluye ese ámbito, para que veas contra qué se ha consultado.

Niveles geográficos

0 país · 1 región · 2 provincia · 3 municipio (por defecto) · 5 distrito · 6 barrio · 7 sección censal · 8 código postal. El 4 no existe en producción.

Tipologías

El campo tipologias es una lista de ID_tipo. La lista viva la sirve GET /api/mercado/tipologias; los habituales son 0 Vivienda, 1 Piso, 2 Casa, 3 Parking, 6 Local, 7 Oficina, 10 Industrial.

Permisos

Cualquier clave habilitada puede leer. Las operaciones que escriben —ingestar, borrar un dataset y recargar la lista de claves— necesitan además la clave de administración; van marcadas con admin más abajo y responden 403 a quien no la tenga.

Errores

Todos con el mismo sobre: { "error": "...", "status": 400 }.

Código	Cuándo
400	Falta un parámetro, o mandas dos orígenes de punto a la vez.
401	Clave ausente, desconocida o deshabilitada.
403	La operación escribe y tu clave no es la de administración.
404	El ámbito no existe en ese nivel, o el recurso no está.
429	Cuota mensual agotada (solo si está activada).

Endpoints

Cosas que conviene saber

• Comparables solo sabe cruzar por municipio. Aunque pidas nivel 6, el ámbito se resuelve a municipio; la respuesta te dice con cuál ha consultado de verdad. Un municipio grande son decenas de miles de filas y puede tardar cerca de un minuto: acota por fechas y por soloPublicados.
• El asking semanal exige fechas. Su tabla tiene decenas de millones de filas y sin acotar se va de tiempo, así que fechaDesde y fechaHasta son obligatorias ahí.
• El contrato se escribe entero: "Venta" o "Alquiler", nunca "V" ni "A".
• Los resultados se cachean. Repetir la misma consulta devuelve duracionMs: 0; no es que no haya hecho nada, es que venía de caché.
• Las consultas de UK vienen acotadas. Un dataset ingestado puede tener cientos de miles de observaciones, así que filtra por area, indicador o periodo; sin filtros te llega el tope y no el conjunto entero.
• Los códigos postales británicos llevan su espacio (PL6 8RU). Se normalizan solos, pero si construyes la URL a mano acuérdate de codificarlo.