Location Lookup via MCP e REST: primeiro o location_id, depois os dados
O Location Lookup é o dicionário gratuito da CASAFARI que converte nomes de lugares ou códigos postais no correspondente location_id. Produtos como o Area Insights ou o Property Sourcing exigem este identificador. Disponível via MCP em https://platform.casafari.com/mcp/locations (ferramenta locations_search) e por API REST, esta consulta custa 0 tokens em qualquer plano (planos e tokens na FAQ para programadores (em inglês), outubro de 2026). Guarde a regra: primeiro o location_id, depois os dados.
Porque é que ‘Cascais’ não chega: distrito, concelho, freguesia e código postal
Imagine um utilizador a perguntar a um assistente de inteligência artificial: «Qual é o preço médio por metro quadrado em Cascais?». À primeira vista, o pedido parece claro. No entanto, em Portugal, Cascais é simultaneamente um dos 308 municípios de Portugal (Wikipédia, 2026) e uma união de freguesias (Cascais e Estoril). O problema agrava-se em casos como Lisboa, que é simultaneamente distrito, concelho e cidade.
A organização territorial portuguesa divide-se em 18 distritos e 2 regiões autónomas, subdivididos em concelhos e em mais de 3.000 freguesias (3.092 freguesias contabilizadas após a reforma administrativa de 2013, segundo dados da Direção-Geral do Território). Nomes como São Pedro, Santa Maria ou Santo António repetem-se em dezenas de concelhos diferentes. Se um agente de IA efetuar uma pesquisa direta apenas pelo texto do nome, arrisca-se a devolver métricas da entidade errada ou a falhar o pedido.
Os códigos postais ajudam a refinar a pesquisa, seguindo o formato do código postal português gerido pelos CTT (XXXX-XXX, como 1000-205 Lisboa; Wikipédia, 2026). O bloco CP4 identifica a zona postal e o CP3 especifica o arruamento ou a subdivisão. Enquanto um ser humano deduz o nível geográfico pelo contexto da conversa, um modelo de linguagem necessita de um identificador unívoco: o location_id.
Como funciona o locations_search via MCP
Para resolver este desafio sem complexidade de programação, a CASAFARI disponibiliza um servidor dedicado no endereço https://platform.casafari.com/mcp/locations. O servidor opera através do protocolo Model Context Protocol (MCP) via Streamable HTTP. A autenticação é simples: no primeiro acesso, o utilizador efetua a autenticação OAuth 2.1 no navegador, sem necessidade de copiar chaves manuais (guia de ligação dos servidores MCP (em inglês), outubro de 2026). No primeiro registo, é ativado automaticamente o plano Free, que inclui 1.000 tokens por 30 dias sem pedir cartão de crédito.
O servidor disponibiliza a ferramenta locations_search. O agente de IA envia os parâmetros de pesquisa, nomeadamente o nome do lugar ou o código postal (query), recebendo em resposta uma lista de candidatos geográficos com os respetivos valores de location_id. O agente pode assim selecionar o identificador exato ou pedir confirmação ao utilizador quando existirem dúvidas entre concelho e freguesia.
Esta integração funciona nativamente numa vasta lista de clientes MCP, incluindo Claude (claude.ai, aplicação de ambiente de trabalho e telemóvel), ChatGPT (modo de programador), Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, Devin Desktop, Zed, Cline, JetBrains Junie, Kiro, Warp e goose.
E via REST: o mesmo dicionário para quem programa
Se está a desenvolver uma aplicação tradicional ou um serviço em segundo plano sem interface interativa, o mesmo dicionário está disponível através de uma API REST tradicional. Basta efetuar um pedido HTTP GET para o endereço https://platform.casafari.com/v1/locations/search?query=Lisboa, enviando o cabeçalho Authorization: Bearer <API key> (repositório público casafari-mcp com exemplos REST (em inglês), outubro de 2026).
As chaves de API podem ser criadas diretamente no painel de controlo em https://platform.casafari.com/console/. A lógica mantém-se idêntica: os identificadores obtidos via REST são os mesmos utilizados via MCP e a consulta custa exatamente 0 tokens. Recomendamos que armazene o location_id em memória cache na sua aplicação para evitar chamadas repetidas.
Para conhecer todos os detalhes técnicos dos endpoints REST, consulte a FAQ sobre o Location Lookup (em inglês) e a página explicativa sobre a Plataforma de Integração de Dados da CASAFARI. Se está a dar os primeiros passos com integração de dados imobiliários, veja também o nosso artigo sobre o que é uma API imobiliária.
Porque é que um agente deve resolver sempre o lugar primeiro
Adotar a regra de converter o local num identificador antes de pedir métricas traz três vantagens essenciais para quem desenvolve assistentes imobiliários:
- Exatidão funcional: as ferramentas analíticas da CASAFARI exigem identificadores numéricos, círculos geográficos ou polígonos. Enviar um nome em texto livre diretamente para uma ferramenta de análise de mercado resulta em erro ou numa seleção arbitrária.
- Eficiência de custos: a pesquisa no Location Lookup custa 0 tokens. Pelo contrário, as chamadas de dados nos restantes produtos consomem os tokens do seu plano (o plano Free oferece 1.000 tokens por 30 dias; o plano Agent custa 49 € por mês na subscrição anual ou 70 € por mês na subscrição mensal, sem IVA; fonte: developers.casafari.com/docs/faq, outubro de 2026). Resolver o local primeiro evita gastar tokens com parâmetros incorretos.
- Transparência na resposta: ao identificar o local, o agente pode confirmar abertamente com o utilizador («A analisar o concelho de Cascais…») antes de processar os dados.
Nas instruções do seu agente (system prompt), pode incluir esta orientação simples:
«Antes de qualquer consulta de dados, resolve o lugar com locations_search e confirma o nível (distrito, concelho, freguesia ou código postal) com o utilizador quando houver mais do que um candidato.»
Ao obter o location_id correto, o seu agente acede à totalidade do o grafo de imóveis da CASAFARI (em inglês) (outubro de 2026), que reúne imóveis residenciais e comerciais limpos e sem duplicados em 16 países (EUA: em fase de entrada, estados selecionados, apenas imobiliário comercial, através do Claro AI). Em Portugal, este identificador serve de base para consultas na documentação do Area Insights (em inglês) e no Property Sourcing; o Comparables (em inglês) trabalha a partir de um ponto, de uma morada ou de um polígono, e o AgentGraph, dedicado à Alemanha, tem a sua própria ferramenta de localização. Para locais comerciais em Espanha ou na Alemanha, o Claro (em inglês) procura a partir de nomes de cidades e províncias, sem location_id.
Por onde começar hoje
Integrar a pesquisa de localizações no seu assistente demora menos de cinco minutos:
- Aceda a
https://platform.casafari.com/para criar conta gratuita na plataforma CASAFARI (sem necessidade de introduzir cartão de crédito). - Adicione o servidor
https://platform.casafari.com/mcp/locationscomo conector personalizado no seu cliente MCP habitualmente utilizado (Claude ou ChatGPT). - Faça um teste prático perguntando: «Qual é o location_id de Alvalade, Lisboa?». Utilize depois o código devolvido para realizar análises no Area Insights.
Para explorar todo o potencial da inteligência artificial aplicada ao setor imobiliário, visite a página do CASAFARI MCP, dados imobiliários para agentes de IA e leia a nossa análise sobre a IA agêntica no setor imobiliário. Se tiver dúvidas sobre a cobertura de uma zona em particular, consulte o nosso artigo explicativo sobre o que fazer quando não encontra uma localização específica ou abra uma conta gratuita na plataforma da CASAFARI. Lembre-se: primeiro o location_id, depois os dados.
Perguntas frequentes
O que é o location_id da Casafari e para que serve?
O location_id é o identificador único e estável de um lugar no grafo imobiliário da CASAFARI. Produtos como o Area Insights e o Property Sourcing exigem um location_id como entrada (o Area Insights aceita também um círculo geográfico), e nunca um texto livre. O Location Lookup é o dicionário gratuito que converte o nome da zona nesse identificador (fonte: developers.casafari.com/docs/connect, outubro de 2026).
Quanto custa usar o Location Lookup via MCP ou API?
A consulta de localizações custa 0 tokens em qualquer plano, incluindo o plano Free, que disponibiliza 1.000 tokens por 30 dias sem necessidade de cartão de crédito. Apenas as chamadas de dados para os restantes produtos consomem tokens do seu saldo. O plano Agent custa 49 € por mês na faturação anual ou 70 € no pagamento mensal, sem IVA, existindo também créditos pré-pagos (fonte: developers.casafari.com/docs/faq, outubro de 2026).
Como ligo o servidor MCP de localizações ao Claude ou ao ChatGPT?
Para ligar o servidor, adicione o endereço https://platform.casafari.com/mcp/locations como conector personalizado nas definições do seu assistente (em Customize > Connectors no Claude ou em Developer mode no ChatGPT). A autenticação é efetuada no navegador através de OAuth 2.1, sem necessidade de copiar chaves manuais, e a conta é criada no primeiro início de sessão no plano Free. Note que o antigo endereço mcp.casafari.com foi descontinuado (fonte: developers.casafari.com/docs/connect, outubro de 2026).
Posso pesquisar por código postal ou por freguesia?
O Location Lookup aceita nomes de localidades e códigos postais no formato XXXX-XXX dos CTT. Caso pretenda confirmar a disponibilidade de uma freguesia específica ou de uma zona postal mais restrita, recomendamos realizar um teste rápido com a ferramenta locations_search no plano Free. Se uma localização não for encontrada, consulte o nosso guia sobre o que fazer quando não encontra uma localização específica.
Preciso de uma chave de API ou basta iniciar sessão?
Para assistentes interativos baseados em MCP (como o Claude Desktop ou o ChatGPT), basta iniciar sessão no navegador via OAuth 2.1 quando solicitado pelo conector. Se estiver a criar um agente autónomo ou um script em segundo plano, deve gerar uma chave de API na consola da plataforma CASAFARI e enviá-la no cabeçalho Authorization: Bearer do endpoint REST /v1/locations/search (fonte: developers.casafari.com/docs/connect-platform, outubro de 2026).