APIs REST da Casafari: o que construir com cada uma e quando preferir o MCP
A plataforma da CASAFARI disponibiliza sete APIs REST assentes num único grafo de imóveis em 16 países (EUA: em fase de entrada, estados selecionados, apenas imobiliário comercial, através do Claro AI), permitindo consultar o histórico de preços e estados de cada imóvel residencial e comercial. A regra de escolha é simples: prefira a API REST quando o seu próprio código decide as chamadas (backends, portais, CRM ou rotinas em lote) e o Casafari MCP quando a decisão cabe a um agente ou assistente de IA. Pode testar a plataforma no plano Free com 1.000 tokens durante 30 dias sem cartão, sendo a pesquisa de localizações (Location Lookup) totalmente gratuita.
Porque é que uma integração vale mais do que uma folha de cálculo em 2026
Os preços das habitações em Portugal subiram 17,6 % em 2025, de acordo com o Índice de Preços da Habitação do INE publicado em março de 2026, com o quarto trimestre a registar um aumento homólogo de 18,9 %. Num mercado que evolui a este ritmo, qualquer indicador de preço por metro quadrado ou relatório de avaliação guardado numa folha de cálculo fica desatualizado em poucos meses.
Imagine o responsável de produto de uma rede imobiliária em Lisboa que dedica a manhã de segunda-feira a atualizar manualmente os valores das freguesias, ou a equipa de análise de risco de um intermediário de crédito a reavaliar garantias com base em ficheiros estáticos. A integração por API não serve apenas para poupar tempo; serve para garantir que as decisões de negócio e os algoritmos da sua aplicação trabalham sempre com dados atualizados. Se procura entender os fundamentos antes de começar a programar, leia o nosso artigo sobre o que é uma API imobiliária.
Location Lookup: transformar «Campo de Ourique» num id de localização (0 tokens)
Todas as restantes APIs da CASAFARI exigem um identificador único de localização (location_id). A API Location Lookup resolve texto livre — como o nome de uma freguesia, concelho ou bairro — nesse identificador exato através do endpoint GET /v1/locations/search.
O caso de uso ideal é a caixa de pesquisa de um portal imobiliário ou de um CRM. À medida que o utilizador escreve «Campo de Ourique» ou «Cedofeita», o sistema devolve o location_id correto sem margem para ambiguidades. Como esta operação consome 0 tokens, pode ser executada a cada toque de tecla na sua interface sem agravar os custos de infraestrutura.
Area Insights: a tendência do preço por m² para um relatório de zona
Com o location_id obtido, a API Area Insights permite extrair indicadores agregados do mercado imobiliário. Pode consultar o preço médio de oferta por metro quadrado, o tempo médio que os imóveis permanecem no mercado e a distribuição de preços por tipologia numa determinada zona.
Esta API responde a dois casos de uso principais descritos nos casos de uso no developers.casafari.com (em inglês): a criação de páginas de mercado dinâmicas no site da sua agência e o cálculo de rentabilidade bruta de arrendamento (rental yield) por zona para plataformas de investimento que comparam concelhos como Braga e Setúbal. Conheça em detalhe a solução na página do produto Insights de Área.
Property Sourcing: pesquisa de imóveis dentro da sua própria aplicação
Para portais ou aplicações proptech que necessitam de apresentar listagens de imóveis para venda ou arrendamento, a API Property Sourcing disponibiliza acesso ao grafo desduplicado da CASAFARI. Em vez de recolher dados de múltiplos portais e lidar com anúncios duplicados, a sua aplicação recebe um único registo consolidado por imóvel.
Cada imóvel inclui o histórico completo de alterações de preço e mudanças de estado. Isto permite que a sua aplicação mostre métricas valiosas como «no mercado há X dias» ou «baixou de preço X %». Veja o nosso estudo de caso sobre como a Casafari construiu a sua aplicação móvel com a própria API para perceber como a arquitetura foi desenhada.
Seller Leads: baixas de preço repetidas para a equipa de angariação
A API Seller Leads (High Potential Seller Leads) apoia a angariação imobiliária identificando, em redor de um ponto, os imóveis cujo preço pedido foi reduzido repetidamente: quantas baixas e qual a percentagem acumulada. Cobre Espanha, França, Itália, Alemanha, Grécia e Andorra; Portugal ainda não está incluído.
Uma rotina programada no seu backend pode consultar diariamente este endpoint para a sua zona de atuação e inserir automaticamente novas tarefas no CRM da equipa comercial. Trata-se de uma recolha de dados ativa executada pelo seu próprio código para alimentar o funil de angariação de forma estruturada. Se pretender aprofundar estratégias de angariação, consulte o nosso guia sobre como a angariação de imóveis de particulares beneficia de processos automatizados.
Comparables & Valuation: avaliação automática para um banco ou um portal
A API Comparables & Valuation gera estimativas de valor de mercado e seleciona imóveis comparáveis com base em critérios geográficos e físicos rigorosos.
Numa chamada típica, o seu código envia um corpo JSON com a operação ("sale"), o tipo de imóvel ("apartment"), a quantidade de comparáveis pretendida e as coordenadas geográficas num raio definido (location_boundary.circle com distância, latitude e longitude). Esta API é amplamente utilizada por entidades financeiras para uma pré-análise de crédito à habitação e por portais que disponibilizam ferramentas de estimativa de valor para captação de proprietários. Importa notar que esta estimativa automática serve de apoio à decisão e não substitui a avaliação formal efetuada por um perito avaliador credenciado.
Claro: localização de lojas em Espanha e na Alemanha (ainda não em Portugal)
O produto Claro foca-se na análise de localização para superfícies comerciais. É importante esclarecer que o Claro cobre atualmente locais comerciais em Espanha e na Alemanha, e terrenos comerciais exclusivamente na Alemanha, não oferecendo cobertura para o mercado português.
Para redes de retalho ou franchisados em Portugal que estejam a planear a expansão para Madrid ou Berlim, esta API permite selecionar lojas com base em critérios de visibilidade e dados de Location Intelligence (como fluxo de transeuntes e áreas de influência). Pode consultar a documentação do Claro (em inglês) e os casos de uso do Claro (em inglês) para conhecer a estrutura de dados.
Account: saber quantos tokens restam antes de lançar o batch
A API Account fornece informações em tempo real sobre o plano ativo e o saldo de tokens disponível na sua conta.
Antes de executar rotinas intensivas em lote — como a reavaliação mensal de uma carteira de imóveis —, o seu código deve consultar este endpoint para garantir que existem tokens suficientes para concluir o processamento sem interrupções. A consulta do estado da conta ajuda a manter a monitorização das suas operações de dados. Para explorar todos os parâmetros disponíveis, consulte a referência da API REST (em inglês).
REST ou MCP: como escolher para cada projeto
A plataforma da CASAFARI permite aceder ao mesmo grafo de imóveis através de duas interfaces distintas: a API REST tradicional e o protocolo MCP (Model Context Protocol).
Escolha a API REST quando a lógica do seu software é determinística e controlada pelo seu código (backends, tarefas em lote, aplicações móveis ou portais). A autenticação é feita via chave de API no cabeçalho Authorization como Bearer token, estando a especificação OpenAPI publicamente disponível.
Escolha o Casafari MCP quando o cliente é um assistente de IA ou agente autónomo (como Claude, ChatGPT, Cursor ou Claude Code) que precisa de descobrir e chamar ferramentas de forma dinâmica. O acesso é feito por produto em endpoints dedicados (platform.casafari.com/mcp/<produto>) com autenticação OAuth 2.1 via navegador. Para analisar as equivalências detalhadas entre as duas abordagens, consulte a tabela de paridade entre REST e MCP (em inglês) e as instruções sobre como ligar um cliente MCP (em inglês). O repositório público casafari/casafari-mcp no GitHub (em inglês) reúne um plugin para o Claude Code, uma extensão para o Gemini CLI e exemplos de código em curl, Python e TypeScript.
Quanto custa e como começar hoje
O modelo de utilização baseia-se em consumos por token. O plano Free atribui 1.000 tokens válidos por 30 dias sem necessidade de inserir cartão de crédito. O plano Agent tem o custo de 49 € por mês no plano anual (ou 70 € mês a mês), acrescido de IVA, existindo também planos Custom por contrato e pacotes de créditos pré-pagos para consumos adicionais. Relembramos que as consultas na API Location Lookup custam 0 tokens. Pode consultar todos os detalhes na página sobre os planos e preços em tokens (em inglês).
Para iniciar a integração, basta criar a conta e a chave na plataforma Casafari, testar a chamada de pesquisa de localizações e implementar a API adequada ao seu projeto. Se desejar saber mais sobre as nossas soluções empresariais, visite a página da API de dados imobiliários da Casafari.
Perguntas frequentes
O que é uma API imobiliária e para que serve?
Uma API imobiliária é uma interface de programação que permite integrar dados do mercado imobiliário — como anúncios, preços de oferta, comparáveis e estatísticas de zona — diretamente nas suas próprias aplicações, CRM ou sistemas de análise. Em vez de consultar portais manualmente, o seu software recebe dados estruturados e limpos em tempo real. A plataforma da CASAFARI disponibiliza uma API REST por produto sobre um grafo desduplicado de imóveis em 16 países, incluindo Portugal.
Qual é a diferença entre a API REST e o Casafari MCP?
A diferença reside no sistema que efetua a chamada aos dados. Na API REST, o código da sua aplicação decide exatamente qual o endpoint a consultar e como processar a resposta JSON utilizando uma chave de API. No Casafari MCP, um agente ou assistente de IA (como Claude ou ChatGPT) descobre as ferramentas e decide autonomamente quais as consultas a realizar, utilizando autenticação OAuth 2.1 no navegador. Ambos acedem ao mesmo grafo de imóveis e partilham o mesmo saldo de tokens.
Quanto custa usar a API da Casafari?
A CASAFARI disponibiliza um plano Free com 1.000 tokens válidos por 30 dias, sem necessidade de cartão de crédito. O plano Agent custa 49 € por mês na faturação anual ou 70 € no plano mensal (valores sem IVA), existindo opções Custom por contrato para volumes elevados. A API Location Lookup não consome tokens (0 tokens), e o consumo de cada uma das restantes operações pode ser acompanhado na documentação oficial.
Como obter o preço por metro quadrado de uma freguesia por API?
O processo realiza-se em dois passos simples. Primeiro, chama a API Location Lookup (GET /v1/locations/search) para converter o nome da freguesia no respetivo identificador único (location_id), uma consulta que custa 0 tokens. Em seguida, utiliza esse identificador na API Area Insights para obter a série histórica e a tendência do preço por metro quadrado da zona. Como os preços da habitação em Portugal subiram 17,6 % em 2025 segundo o INE, recomenda-se a atualização mensal destes dados na sua aplicação.
A API da Casafari permite encontrar imóveis de particulares em Portugal?
Não através da Seller Leads: a High Potential Seller Leads devolve imóveis cujo preço pedido foi reduzido repetidamente em redor de um ponto, em Espanha, França, Itália, Alemanha, Grécia e Andorra, e nunca contactos de proprietários. Para Portugal, utilize a API Property Sourcing, que devolve um registo único por imóvel e o seu histórico de preços com expand=history. O backend da sua aplicação pode executar consultas diárias por localização e criar tarefas no CRM da sua equipa de angariação.