Qué construir con cada API REST de CASAFARI: un caso de uso por producto (y cuándo elegir REST o MCP)
La plataforma CASAFARI expone sus datos sobre un grafo unificado de inmuebles presente en 16 países (en Estados Unidos, CASAFARI está entrando ahora en estados seleccionados, solo con inmuebles comerciales y a través de Claro AI) a través de API REST especializadas por producto. Permiten integrar desde un widget de valoración automática en la ficha de un inmueble hasta un buscador con posición GPS o la detección diaria de viviendas con bajadas de precio repetidas. La llamada a Location Lookup cuesta 0 tokens y es el punto de partida habitual para el resto de endpoints. Para productos propios y automatizaciones deterministas conviene utilizar la API REST; para asistentes conversacionales y agentes de IA, los servidores MCP.
Un equipo de desarrollo en una proptech de Madrid recibe el backlog del próximo trimestre. El primer ticket pide implementar una valoración automática en la ficha del inmueble para el mercado residencial. El segundo exige un panel de captura de particulares para los asesores captadores de Salamanca y Chamberí. El tercero plantea un buscador por mapa en la aplicación móvil.
La duda habitual en estas reuniones no es si los datos existen, sino a qué endpoint llamar para resolver cada historia de usuario sin reprogramar la lógica de negocio. Para responder a esa pregunta conviene repasar los productos que ofrece la plataforma en platform.casafari.com y la documentación técnica pública disponible en developers.casafari.com.
Location Lookup: el primer paso de cualquier integración
Cualquier consulta geográfica en el ecosistema de CASAFARI empieza resolviendo un nombre de zona o una dirección hacia un identificador interno de ubicación. Si un usuario escribe «Chamberí», «Poblenou» o «Nueva Andalucía» en un campo de texto, la aplicación debe transformar esa cadena en un id oficial antes de pedir series temporales o propiedades comparables.
La operación GET /v1/locations/search recibe un nombre de lugar o un código postal y devuelve los identificadores de ubicación correspondientes; GET /v1/locations/{location_id} añade su jerarquía (provincia, municipio, distrito, barrio). Esta llamada tiene un coste de 0 tokens, según las preguntas frecuentes para desarrolladores de CASAFARI (en inglés) (octubre de 2026). La recomendación técnica es almacenar en caché los identificadores devueltos: los nombres comerciales de los barrios pueden variar o presentar erratas, pero las claves geográficas permanecen estables.
Si durante una búsqueda una dirección concreta no devuelve coincidencias, conviene revisar qué hacer si no aparece una ubicación en el centro de ayuda de la plataforma.
Area Insights: la tendencia del precio por metro cuadrado de un barrio
El equipo de producto de un portal inmobiliario o de la división inmobiliaria de un banco necesita mostrar un gráfico interactivo con la evolución del precio por metro cuadrado en los últimos 24 meses. La API REST de Area Insights proporciona series temporales, distribuciones por tramos de precio y dormitorios, tiempo de permanencia en el mercado y análisis de mercado; los mapas de calor por distrito solo están disponibles a través del servidor MCP.
Al enviar la clave de ubicación obtenida previamente a los endpoints analíticos explicados en la documentación de Area Insights (en inglés), la aplicación recupera la información estadística limpia para construir interfaces comparativas entre distritos adyacentes, como Salamanca frente a Puente de Vallecas.
Un segundo caso muy demandado para este endpoint es el cálculo de la rentabilidad bruta del alquiler por zona. Al cruzar las series temporales de oferta de venta con las series de oferta de arrendamiento para una misma tipología de vivienda, los analistas de inversión obtienen el porcentaje estimado de rendimiento sin tener que agregar manualmente portales externos. Se puede ampliar este análisis en las páginas de Insights de Zona y en la guía sobre qué es una API inmobiliaria.
Property Sourcing: un buscador de inmuebles dentro de la propia app
Las aplicaciones móviles para compradores e inversores exigen un motor de búsqueda que filtre anuncios duplicados y entregue el historial completo de precios de cada propiedad. El grafo de inmuebles de CASAFARI consolida anuncios procedentes de múltiples fuentes en un único registro por propiedad con su historial de precios y estados de publicación.
Mediante la API de Property Sourcing, detallada en la documentación de Property Sourcing (en inglés), la aplicación resuelve las coordenadas GPS del dispositivo a identificadores de zona con GET /v1/locations/by-coordinates y los envía como location_ids a POST /v1/property-sourcing/searches. El servicio responde con un único registro por inmueble, con su precio, precio por metro cuadrado, dormitorios, superficie, coordenadas y fecha de primera aparición en el mercado.
Un ejemplo real de esta arquitectura se analiza en el caso de la app móvil construida sobre la API de CASAFARI, donde la integración con el catastro español y la geolocalización por radio permiten a los usuarios consultar inmuebles disponibles mientras caminan por la calle.
Seller Leads: viviendas con bajadas de precio repetidas cerca de un punto
Para los equipos de captación de las agencias inmobiliarias y las redes franquiciadas en España, alimentar el CRM de forma automatizada ahorra horas de rastreo manual. La API de Seller Leads devuelve las viviendas situadas en un radio de 50 a 300 metros de un punto cuyo precio de venta o alquiler ha bajado varias veces, con el número de bajadas y el porcentaje acumulado, en España, Francia, Italia, Alemania, Grecia y Andorra, sin datos personales de los propietarios.
El patrón de integración recomendado consiste en una tarea programada (job de backend) que consulta periódicamente las operaciones de Seller Leads expuestas en la documentación de Seller Leads (en inglés). Cada mañana, el proceso llama a GET /v1/seller-leads alrededor de la ubicación de cada oficina y asigna automáticamente al asesor correspondiente las viviendas cuyo precio ha bajado desde la última ejecución (parámetro since).
El mismo endpoint admite un número mínimo de bajadas y un porcentaje acumulado configurables, y GET /v1/seller-leads/{lead_id} devuelve el historial fechado de precios y estados de cada vivienda. Así los asesores llegan primero a los propietarios con más motivos para vender; el contacto lo hacen siempre ellos, por los canales de la agencia. Para estructurar los procesos comerciales de captación, es útil revisar los consejos sobre captación de inmuebles de particulares.
Comparables & Valuation: una valoración automática en la ficha del inmueble
La valoración en tiempo real exige encontrar inmuebles representativos que hayan sido comercializados o estén actualmente en oferta en el entorno inmediato de la propiedad evaluada.
Según la especificación técnica publicada en el repositorio público casafari-mcp en GitHub (octubre de 2026), una petición tipo de valoración exige enviar una cabecera de autenticación Bearer con la clave de API y un cuerpo JSON con los siguientes campos:
operation: tipo de transacción (salepara venta orentpara alquiler).comparables_types: tipología del inmueble (piso, casa, etc.).comparables_count: número de propiedades comparables requeridas para la muestra.location_boundary: círculo geográfico definido por latitud, longitud y radio en kilómetros.
{
"operation": "sale",
"comparables_types": ["apartment"],
"comparables_count": 10,
"location_boundary": {
"circle": {
"distance": 1.0,
"target_point": {
"coordinates": {
"latitude": 40.4168,
"longitude": -3.7038
}
}
}
}
}En el mercado español, la referencia catastral ayuda en la valoración inmobiliaria al proporcionar los metros cuadrados construidos y el año de construcción oficiales. Los parámetros están en la documentación de Comparables & Valuation (en inglés) y la solución de Valoraciones y Estudio de Mercado.
Claro AI: locales comerciales a partir de un brief en lenguaje natural
La búsqueda de activos comerciales difiere del mercado residencial por la complejidad de sus requerimientos técnicos. Claro AI procesa solicitudes descritas en lenguaje natural para el segmento terciario.
Un departamento de expansión de una cadena de restauración o una consultora inmobiliaria en Valencia puede enviar una consulta como: «Local de 150 m² con salida de humos y fachada mínima de 8 metros en la zona de Ruzafa». La API procesa el texto y devuelve la lista de inmuebles comerciales que cumplen las especificaciones operativas.
Es imprescindible tener presente la cobertura geográfica del producto descrita en la documentación de Claro (en inglés) (octubre de 2026): Claro AI cubre locales comerciales en España y Alemania, y parcelas comerciales únicamente en Alemania. No aplica a otros países ni a otros tipos de activos.
Account: saber cuántos tokens quedan antes de que el servicio se pare
Las integraciones en producción requieren supervisar el consumo de recursos de la plataforma para evitar interrupciones no planificadas en las herramientas orientadas al cliente final.
La API de Account permite consultar desde el backend el estado de la suscripción y el saldo de tokens disponibles. La recomendación es crear un monitor interno que ejecute una llamada diaria a este endpoint y active una alerta cuando el saldo descienda por debajo de un umbral prefijado.
De acuerdo con la FAQ de desarrolladores de CASAFARI (octubre de 2026), la estructura de costes se organiza en planes de consumo medidos en tokens:
| Plan | Tokens incluidos | Duración | Precio (IVA no incluido) |
|---|---|---|---|
| Free | 1.000 tokens | 30 días | 0 € |
| Agent (anual) | 1.500 tokens al mes (máximo de 600 tokens por ventana de 3 horas) | Facturación anual | 39 € / mes (468 € / año) |
| Agent (mensual) | 1.500 tokens al mes (máximo de 600 tokens por ventana de 3 horas) | Facturación mes a mes | 49 € / mes |
| Custom | A medida | Según contrato | Según propuesta |
El uso adicional se paga con tokens prepagados. Las búsquedas en Location Lookup no consumen tokens (0 tokens).
¿REST o MCP? Cómo elegir según lo que se construye
Una de las decisiones arquitectónicas principales en 2026 es determinar la interfaz adecuada entre la API REST tradicional y los servidores MCP (Model Context Protocol).
El criterio de selección se fundamenta en quién consume el servicio:
- API REST, para una aplicación web propia, un backend, un proceso ETL de carga de datos o un widget determinista en el que el código hace llamadas explícitas con una clave de API.
- MCP, cuando los usuarios trabajan con asistentes conversacionales o agentes de IA (como Claude, ChatGPT, Cursor, VS Code o Claude Code) que deben descubrir herramientas de forma dinámica y tomar decisiones de consulta autónomas.
Según la guía de conexión de CASAFARI (octubre de 2026), existe un servidor MCP independiente por producto alojado en la ruta https://platform.casafari.com/mcp/<producto> (locations, area-insights, comparables, agentgraph y claro). Estos servidores funcionan con transporte Streamable HTTP y autenticación OAuth 2.1 directamente en el navegador, sin necesidad de copiar manualmente claves secretas.
Ambas opciones acceden al mismo grafo de inmuebles de CASAFARI (en inglés) de 16 países y consumen la misma cuenta de tokens. Las equivalencias completas están en CASAFARI MCP para agentes de IA y en la tabla de comparativa entre MCP y REST (en inglés).
Por dónde empezar esta semana
Para empezar la integración, tres pasos:
- Crear una cuenta gratuita en platform.casafari.com para disponer de 1.000 tokens durante 30 días sin introducir datos de pago.
- Hacer una primera llamada a
GET /v1/locations/searchpara obtener la clave geográfica de la ciudad o barrio de interés en España. - Revisar los casos de uso en developers.casafari.com (en inglés) y las ventajas de la API inmobiliaria de CASAFARI para elegir el endpoint que resuelve el ticket prioritario del equipo.
La página de las API de datos inmobiliarios de CASAFARI reúne la documentación y los primeros pasos para configurar las claves de API.
Preguntas frecuentes
¿Qué se puede hacer con la API REST de CASAFARI?
La API REST de CASAFARI permite conectar aplicaciones cliente con un grafo de datos inmobiliarios en 16 países. Ofrece endpoints específicos para resolver ubicaciones (Location Lookup), analizar tendencias y precios por metro cuadrado (Area Insights), integrar motores de búsqueda de inmuebles (Property Sourcing), detectar viviendas con bajadas de precio repetidas cerca de un punto (Seller Leads), calcular valoraciones automáticas (Comparables & Valuation) y buscar locales comerciales a partir de una descripción (Claro AI). Los detalles están en los casos de uso de developers.casafari.com.
¿Cuál es la diferencia entre la API REST y el servidor MCP de CASAFARI?
La API REST está diseñada para ser llamada directamente por aplicaciones, procesos en segundo plano y sistemas deterministas mediante una clave de API. Por su parte, los servidores MCP (Model Context Protocol) permiten a agentes de IA y asistentes como Claude o Cursor descubrir y ejecutar consultas de forma autónoma con autenticación OAuth 2.1. Ambas interfaces comparten el mismo grafo de propiedades, la misma cuenta y la misma bolsa de tokens.
¿Cuánto cuesta usar la API de CASAFARI?
La plataforma dispone de un plan Free que otorga 1.000 tokens durante 30 días sin solicitar tarjeta de crédito. El plan Agent tiene un coste de 49 € al mes con facturación mensual o de 39 € al mes (468 € al año) con facturación anual (IVA no incluido) e incluye 1.500 tokens al mes (máximo 600 tokens cada 3 horas), mientras que las necesidades a gran escala se articulan mediante planes Custom por contrato. El consumo adicional se gestiona mediante tokens prepagados, y las llamadas al endpoint Location Lookup son gratuitas (0 tokens), según la FAQ oficial de desarrolladores a fecha de octubre de 2026.
¿Cómo se integra una valoración automática de viviendas en una web?
Primero se obtiene el punto de referencia del inmueble: sus coordenadas, su dirección o su referencia catastral, ya que Comparables & Valuation acepta cualquiera de las tres. A continuación se hace una petición al servicio de Comparables & Valuation especificando el tipo de transacción, la clase de inmueble y el radio de búsqueda deseado. La respuesta entregará una muestra de propiedades comparables y la estimación de valor esperada para mostrarla directamente en el widget del portal. La guía completa está en la documentación de Comparables & Valuation de developers.casafari.com.
¿Funciona Claro AI para locales comerciales en toda España?
Sí. Claro AI cubre locales comerciales en venta y en alquiler en toda España y en Alemania, a partir de un encargo descrito en lenguaje natural. Las parcelas para uso comercial solo están disponibles en Alemania, según la documentación de Claro AI.