Location Lookup por MCP y REST: cómo convertir un nombre de lugar en un location_id de Casafari

Location Lookup es el diccionario de lugares de CASAFARI que permite convertir el nombre de cualquier municipio, distrito, barrio o código postal en un location_id único. La herramienta locations_search tiene un coste de 0 tokens y constituye el paso previo imprescindible para consultar otros productos como Area Insights, Comparables o Property Sourcing. Está disponible mediante el servidor MCP en https://platform.casafari.com/mcp/locations y a través de un endpoint REST.

Qué hace Location Lookup y por qué es el primer paso

Si un usuario le pide a un asistente de inteligencia artificial «un análisis de precios en Salamanca», el sistema se enfrenta a una ambigüedad inmediata. ¿Se refiere a la ciudad de Salamanca en Castilla y León, a la provincia homónima o al Barrio de Salamanca en el centro de Madrid? España cuenta con 8.132 municipios (Instituto Nacional de Estadística, 2025) y una población de 49.128.297 habitantes (INE, censo a 1 de enero de 2025), lo que genera una amplia repetición de topónimos y delimitaciones administrativas superpuestas.

Para una base de datos de análisis inmobiliario como la de CASAFARI, una cadena de texto libre no es una dirección inequívoca. Los motores de análisis espacial de la plataforma requieren identificadores estructurados para operar con precisión. Aquí es donde interviene Location Lookup: una herramienta diseñada para resolver cualquier denominación en un location_id estandarizado antes de invocar cualquier cálculo o consulta de datos.

Cómo funciona locations_search: del nombre al location_id

El funcionamiento de la herramienta locations_search se basa en recibir un texto de búsqueda genérico (por ejemplo, «Chamberí», «28010» o «Vigo»). Como respuesta, el sistema devuelve un listado de candidatos ordenados por relevancia, indicando para cada uno su location_id, el tipo de entidad geográfica (municipio, distrito, barrio o código postal) y su jerarquía territorial superior.

En el mercado español, un agente de IA se encontrará habitualmente con cinco niveles de organización administrativa:

• Comunidad autónoma
• Provincia (52 provincias y ciudades autónomas)
• Municipio (8.132 según el INE en 2025)
• Distrito
• Barrio o código postal

Una vez obtenido el location_id correcto, este identificador actúa como la clave de paso principal para el resto del ecosistema de CASAFARI. Se introduce directamente en la documentación de Area Insights (en inglés) para generar estadísticas de mercado de Insights de Zona, en la documentación de Comparables (en inglés) para realizar valoraciones automáticas, o en la documentación de Property Sourcing (en inglés) para buscar inmuebles en venta o en alquiler.

Cuánto cuesta: 0 tokens, y qué significa eso para un agente

Las consultas en Location Lookup no consumen créditos de procesamiento: tienen un coste de 0 tokens en todos los planes de la plataforma (según las preguntas frecuentes sobre planes y tokens, a 23 de octubre de 2026). El plan Free incluye 1.000 tokens válidos durante 30 días sin solicitar tarjeta de crédito, mientras que el plan Agent tiene una tarifa de 49 EUR al mes en facturación anual (o 70 EUR mes a mes, sin IVA), permitiendo adquirir créditos de prepago para uso adicional.

Esta gratuidad en la resolución de ubicaciones permite que un agente conversacional o una integración backend ejecute cuantas búsquedas, aclaraciones o reintentos necesite con el usuario antes de realizar una llamada de pago. Resolver primero el lugar evita el gasto innecesario de tokens en análisis de mercado o comparables ejecutados sobre zonas equivocadas.

Conviene distinguir entre los tokens de consumo de uso de la API/MCP y los tokens de acceso (access tokens) emitidos durante el inicio de sesión OAuth 2.1 para la autenticación de la sesión. Los primeros miden el consumo de las herramientas de pago; los segundos gestionan la seguridad del servicio.

Por MCP: conectar Claude, ChatGPT o Cursor a https://platform.casafari.com/mcp/locations

CASAFARI estructura su arquitectura MCP ofreciendo un servidor dedicado por producto. Para la búsqueda y resolución de lugares, la dirección del servidor es https://platform.casafari.com/mcp/locations. Este servicio utiliza el transporte Streamable HTTP y el protocolo de autenticación OAuth 2.1 en el navegador, lo que elimina la necesidad de copiar manualmente claves secretas; la cuenta de usuario puede crearse en ese primer inicio de sesión, en el plan Free y sin tarjeta (guía para conectar cualquier servidor MCP de Casafari, en inglés, 23 de octubre de 2026).

Este servidor se puede añadir fácilmente a una amplia gama de clientes compatibles con MCP:

• Claude (en claude.ai, aplicación de escritorio y móvil mediante conector personalizado)
• ChatGPT (en modo desarrollador mediante conector personalizado)
• Entornos de desarrollo como Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI, Devin Desktop, Zed, Cline, JetBrains Junie, Kiro, Warp o goose

Para maximizar la eficiencia, se recomienda añadir una regla clara en las instrucciones de sistema (system prompt) del agente: «Antes de invocar cualquier herramienta de datos inmobiliarios de CASAFARI sobre una zona, llama a locations_search para obtener el location_id exacto». Se pueden consultar más detalles sobre la integración de asistentes en la página de Casafari MCP, datos inmobiliarios para agentes de IA y profundizar en cómo un agente de IA automatiza el crecimiento de una inmobiliaria.

Por REST: la misma búsqueda desde cualquier backend

Para aplicaciones tradicionales o servicios backend que no utilicen la arquitectura MCP, la resolución de lugares está disponible mediante un endpoint HTTP REST estándar. La petición requiere un encabezado de autorización HTTP de tipo Bearer con la clave de API creada previamente en la consola de gestión en platform.casafari.com (tal como se detalla en el repositorio público casafari-mcp en GitHub, octubre de 2026).

Una consulta típica para el distrito de Chamberí en Madrid se realiza mediante la siguiente llamada en cURL:

curl -X GET "https://platform.casafari.com/v1/locations/search?query=Chamber%C3%AD" \
  -H "Authorization: Bearer TU_CLAVE_API_AQUI"

La respuesta JSON estructurada devuelve un listado con las coincidencias encontradas (ejemplo ilustrativo):

[
  {
    "location_id": 12345,
    "name": "Chamberí",
    "type": "district"
  }
]

Mientras que el acceso vía MCP utiliza el flujo de inicio de sesión OAuth 2.1 desde el navegador, la API REST emplea la clave de API tradicional generada en el panel del desarrollador. Ambos métodos consultan la misma base de datos sustentada por el grafo de propiedades de Casafari (en inglés), que consolida la información limpia y libre de duplicados de inmuebles residenciales y comerciales en venta y alquiler en 16 países (EE. UU.: en plena entrada, estados seleccionados, solo inmuebles comerciales, con Claro AI). Para ampliar información sobre la integración por API, consulte la sección sobre las APIs de datos inmobiliarios de CASAFARI y la guía sobre qué es una API inmobiliaria.

Errores que evita resolver primero la ubicación

Omitir el paso de resolución inicial suele provocar tres tipos de fallos habituales en las aplicaciones automatizadas:

1. Homónimos geográficos: Nombres como «Santa Cruz» o «Villanueva» existen en múltiples provincias españolas. Sin especificar el contexto o verificar el listado, el agente corre el riesgo de seleccionar la provincia o municipio equivocado.
2. Jerarquías anidadas: Lugares emblemáticos como el Barrio de Salamanca pertenecen al municipio de Madrid. Confundir el barrio con el municipio completo alterará drásticamente los promedios de valor por metro cuadrado.
3. Códigos postales colindantes: Un mismo código postal puede abarcar zonas de más de un distrito, como ocurre en el centro de Madrid. Identificar la delimitación exacta garantiza la precisión de los análisis territoriales.

La norma para cualquier agente inteligente debe ser estricta: si locations_search devuelve más de un candidato, el sistema debe solicitar una aclaración al usuario o seleccionar el candidato cuya jerarquía coincida con el contexto de la conversación. Nunca debe adivinarse un identificador. Para profundizar sobre el modelo de asignación geográfica, conviene revisar la documentación de soporte sobre cómo determina CASAFARI la ubicación de un inmueble y seguir las indicaciones sobre qué hacer si no encuentra una ubicación concreta.

Para comenzar a integrar la búsqueda de lugares en sus proyectos sin consumo de crédito, cree una cuenta gratuita en platform.casafari.com y conecte su asistente o backend a la plataforma.

Preguntas frecuentes

¿Qué es un location_id de Casafari?

El location_id es el identificador único y estable que CASAFARI asigna a cada entidad geográfica dentro de su catálogo de ubicaciones, como municipios, distritos, barrios o códigos postales. Herramientas como Area Insights, Comparables o Property Sourcing requieren este identificador en lugar de texto libre para ejecutar sus consultas de datos. La herramienta Location Lookup permite obtener este código a partir de cualquier nombre de lugar.

¿Cuánto cuesta usar Location Lookup?

El uso de Location Lookup tiene un coste de 0 tokens en todos los planes de CASAFARI, incluido el plan Free que ofrece 1.000 tokens durante 30 días sin solicitar tarjeta de crédito. Los planes de pago, como el plan Agent por 49 EUR al mes con facturación anual o 70 EUR mes a mes (sin IVA), cobran tokens únicamente al consultar las herramientas de datos analíticos. Esto permite realizar todas las búsquedas de ubicación necesarias sin consumir el saldo de procesamiento.

¿Cómo conecto Claude o ChatGPT al servidor MCP de Location Lookup?

Para conectar Claude o ChatGPT, añada la URL https://platform.casafari.com/mcp/locations como un conector personalizado o en el modo desarrollador del cliente. El servidor utiliza el transporte Streamable HTTP y requiere autenticación OAuth 2.1 en el navegador, y en ese primer inicio de sesión se puede crear la cuenta en el plan Free, sin tarjeta. El mismo procedimiento es válido para Cursor, VS Code, Claude Code y otros entornos compatibles con MCP.

¿Puedo buscar un código postal o un barrio, no solo una ciudad?

Sí, la herramienta locations_search permite buscar tanto ciudades como distritos, barrios específicos y códigos postales en España. La respuesta detalla el tipo de entidad geográfica y su estructura jerárquica para que el sistema pueda distinguir correctamente entre los diferentes niveles territoriales. Si una ubicación de tamaño muy reducido no aparece en los resultados, se recomienda consultar la guía de soporte sobre qué hacer cuando no se encuentra un lugar concreto.

¿Por qué mi agente de IA debe llamar primero a locations_search?

Las herramientas de análisis e información inmobiliaria de CASAFARI requieren identificadores geográficos o coordenadas precisas en lugar de texto libre. Dado que en España existen 8.132 municipios (INE, 2025) y frecuentes duplicidades o anidamientos de nombres, resolver la ubicación en un location_id como primer paso garantiza la exactitud del análisis. Además, al costar 0 tokens, esta verificación previa evita malgastar saldo en consultas sobre zonas erróneas.