API REST CASAFARI: cosa costruire con ciascuna (e quando preferire MCP)

Lunedì mattina, ufficio prodotto di una rete immobiliare in franchising a Bologna. Sul tavolo della product manager arrivano tre richieste ben distinte: inserire un modulo di stima immediata sul sito web, mostrare l’andamento del prezzo al metro quadro nelle pagine quartiere di Milano e inviare ogni mattina ai CRM degli agenti gli immobili di zona con ribassi di prezzo ripetuti. Ognuna di queste funzionalità corrisponde a uno specifico servizio dell’architettura CASAFARI.

La piattaforma CASAFARI mette a disposizione una API REST dedicata per ogni prodotto (Location Lookup, Area Insights, Property Sourcing, High Potential Seller Leads, Comparables & Valuation, Claro AI e Account) e server MCP, collegati al medesimo account, per Location Lookup, Area Insights, Comparables, AgentGraph AI e Claro AI. La regola di scelta è semplice: si preferisce l’API REST quando è il codice dell’applicazione a decidere l’esecuzione in modo automatico o programmato; si sceglie MCP quando l’interazione avviene in linguaggio naturale con un utente o un agente d’intelligenza artificiale. Per iniziare a sviluppare, il piano Free offre 1.000 token gratuiti per 30 giorni senza inserire la carta di credito, come specificato alla voce piani e token nelle FAQ per sviluppatori (in inglese) aggiornate al 23 ottobre 2026, con le chiamate di risoluzione dei luoghi tramite Location Lookup a 0 token.

Cosa offre la piattaforma CASAFARI a chi sviluppa

Al centro dell’infrastruttura di CASAFARI risiede il property graph: un archivio unico per immobili residenziali e commerciali, in vendita e in affitto, esteso a 16 paesi (Stati Uniti: ingresso in corso, Stati selezionati, solo immobili commerciali, con Claro AI), secondo quanto documentato nel property graph CASAFARI (in inglese) ad ottobre 2026. Attraverso processi avanzati di deduplica e pulizia dei dati, gli annunci raccolti da decine di portali immobiliari, siti di agenzia e aggregatori vengono unificati in una singola scheda per immobile, completa di storico dei prezzi e dei cambiamenti di stato.

Per il mercato italiano, le API di dati immobiliari CASAFARI combinano l’aggregazione dei portali con i dati reali dei prezzi di compravendita registrati presso le fonti ufficiali, come confermato nel caso di studio dell’app mobile (in inglese) del 2025. In questo modo gli sviluppatori integrano nel proprio software non soltanto l’offerta degli annunci attivi, ma anche lo storico effettivo del transato. Dalla console su platform.casafari.com si gestisce un unico account per generare le chiavi API REST e configurare contemporaneamente l’accesso ai server CASAFARI MCP per agenti IA. Se occorre approfondire i concetti base prima di integrare il codice, è disponibile la guida che spiega che cos’è un’API immobiliare.

Location Lookup: da «Porta Romana, Milano» a un id di zona

Prima di richiedere le metriche di mercato o la stima di un immobile, occorre identificare con precisione la posizione geografica. Il servizio Location Lookup trasforma la stringa testuale digitata da un utente (ad esempio un comune, un quartiere o un indirizzo specifico) in un identificatore univoco di zona (location id) riconosciuto da tutte le altre API del sistema.

Nel contesto aziendale, Location Lookup serve a gestire le caselle di ricerca con completamento automatico (typeahead) all’interno di un portale web o di un’applicazione mobile. Rappresenta inoltre il primo passaggio fondamentale in qualsiasi procedura batch per i CRM: quando un agente seleziona il proprio quartiere di competenza, il software converte la posizione una sola volta, memorizza il location id e lo riutilizza per le interrogazioni successive.

Trattandosi dell’operazione di ingresso della piattaforma, le chiamate a Location Lookup comportano un consumo pari a 0 token su qualsiasi piano attivo. Gli sviluppatori possono quindi normalizzare migliaia di indirizzi durante le fasi di importazione senza intaccare il plafond di token del proprio abbonamento.

Area Insights: il prezzo al metro quadro e il rendimento locativo per quartiere

Mostrare l’andamento del mercato locale è una delle funzionalità più richieste dai portali immobiliari e dalle piattaforme per investitori. Consultando i casi d’uso su developers.casafari.com (in inglese), si individuano due applicazioni chiave per questo servizio: il trend del prezzo al metro quadro e il rendimento locativo per zona.

Attraverso il servizio Area Insights, una pagina quartiere dedicata a Porta Romana a Milano o al quartiere Prati a Roma può mostrare la media dei prezzi richiesti per metro quadro per la vendita e la locazione negli ultimi mesi. Allo stesso modo, le banche o i portali per investitori utilizzano le chiamate di Area Insights per calcolare la redditività lorda stimata della locazione in ciascuna micro-zona, supportando la valutazione del rischio per la concessione di mutui.

Il flusso operativo prevede l’invio del location id ottenuto da Location Lookup unitamente all’intervallo temporale desiderato. Per ottimizzare il consumo dei token, la buona pratica di sviluppo suggerisce di salvare in cache il risultato restituito dall’API per ogni zona su base giornaliera.

Property Sourcing: un’API di ricerca immobili per la tua app

Costruire un motore di ricerca immobiliare nativo all’interno di un’applicazione mobile o di un portale di rete richiede un’infrastruttura di dati solida. Invece di sviluppare complessi sistemi proprietari di scraping dei portali, le proptech e le reti in franchising utilizzano l’API di Property Sourcing per interrogare direttamente il grafo immobiliare unificato di CASAFARI.

La garanzia della qualità dell’API è testimoniata dal fatto che l’app mobile CASAFARI costruita sulla stessa API utilizza esattamente la medesima architettura di ricerca anche per il territorio italiano. Tramite parametri di filtraggio per zona, tipologia di immobile, prezzo, superficie e caratteristiche, l’applicazione riceve risultati privi di duplicati.

Ciascun risultato riporta la data di prima pubblicazione (first_seen); la lettura della scheda con expand=history aggiunge la cronologia datata delle variazioni di prezzo e di stato. Questo permette agli sviluppatori di mostrare etichette informative come «Prezzo ribassato» o «Nuovo sul mercato» senza dover scrivere logiche aggiuntive di calcolo.

High Potential Seller Leads: i ribassi di prezzo ripetuti direttamente nel CRM

L’attività di acquisizione immobiliare con CASAFARI costituisce il fattore critico di successo per qualsiasi agenzia in Italia. Individuare gli immobili il cui prezzo richiesto è stato ribassato più volte, segnale di proprietari disposti a trattare, rappresenta una fonte costante di nuovi mandati.

L’API High Potential Seller Leads (denominata Seller Leads nel prosieguo operativo) consente di integrare queste informazioni all’interno del CRM aziendale tramite chiamate programmate su base giornaliera (polling). Ogni mattina, il sistema dell’agenzia interroga l’API attorno a un punto (raggio da 50 a 300 metri) per scaricare gli immobili della zona il cui prezzo richiesto è stato ribassato più volte, usando il parametro since per contare solo i ribassi dall’ultima esecuzione, e assegna le schede agli agenti di zona. Ogni lead rimanda alla scheda dell’immobile e al suo storico; non vengono restituiti nomi o contatti dei proprietari.

Trattandosi di un’integrazione di tipo batch eseguita via software, l’infrastruttura opera in modo deterministico e sicuro, offrendo ai consulenti immobiliari dati pronti all’uso prima di iniziare le chiamate di acquisizione.

Comparables & Valuation: la stima automatica nel sito di una rete o di una banca

Offrire una valutazione immobiliare immediata online è uno dei metodi più efficaci per acquisire contatti di venditori qualificati o per pre-valutare le richieste di mutuo da parte degli istituti di credito.

L’API Comparables & Valuation alimenta i widget di stima automatica (AVM). Si invia al sistema una richiesta in formato JSON contenente i dati dell’immobile (indirizzo, superficie, tipologia, numero di locali) e l’indicazione del tipo di operazione ("operation": "sale" oppure "rent"), autenticata con l’intestazione standard Authorization: Bearer <API key>, secondo le specifiche del riferimento REST documentato a ottobre 2026.

L’API restituisce un intervallo di valore stimato e la lista degli immobili comparabili utilizzati per il calcolo. L’algoritmo di CASAFARI elabora sia le offerte attive sul mercato sia i dati reali delle compravendite concluse disponibili per l’Italia, garantendo una valutazione accurata visibile sui portali cliente tramite il modulo Valutazioni & Studio di Mercato.

Claro AI: locali commerciali in Spagna e Germania, terreni commerciali in Germania

Per i brand italiani del retail, della ristorazione o del franchising che pianificano l’espansione della propria rete all’estero, CASAFARI mette a disposizione le funzionalità di Claro tramite API REST e server MCP dedicati.

Il raggio di copertura di Claro è ben definito: ricerca e analizza locali commerciali in affitto o in vendita in tutta la Spagna e la Germania (un paese per ricerca) e, separatamente, terreni a destinazione commerciale in Germania. Al 15 ottobre 2026, secondo i dati riportati nella guida di Claro alla selezione di sedi in Spagna (in inglese), Claro indicizza 7.032 locali commerciali retail a Madrid (3.875 in affitto e 4.227 in vendita) e 7.270 a Barcellona (4.835 in affitto e 4.545 in vendita), ciascuno rilevato singolarmente.

Inviando un brief di espansione (superficie desiderata, presenza di canna fumaria, budget di locazione), l’API esegue le operazioni di ricerca, raffinamento dei filtri, confronto delle sedi ed esame della posizione. È possibile consultare la documentazione di Claro (in inglese) e i casi d’uso di Claro (in inglese) per integrare la selezione delle sedi nei propri sistemi di sviluppo commerciale.

Account: chiavi, token e consumo sotto controllo

I team di sviluppo devono mantenere la piena visibilità sui consumi delle API per evitare interruzioni di servizio. L’API di Account consente di realizzare piccoli pannelli di controllo interni per monitorare il piano attivo, il saldo dei token e il consumo mensile.

I piani disponibili sulla piattaforma prevedono la seguente struttura:

• Free: include 1.000 token per 30 giorni, senza richiesta di carta di credito.
• Agent: 49 € al mese con fatturazione annuale oppure 70 € con fatturazione mese per mese, IVA esclusa.
• Custom: contratti su misura per grandi volumi con crediti prepagati per la gestione dei consumi extra.

Tutte le chiamate a Location Lookup consumano 0 token. La gestione delle chiavi API e dei client OAuth si effettua nella console su platform.casafari.com. Nel codice dell’applicazione, il conteggio del consumo usa esclusivamente il termine «token», distinguendo i token di consumo del piano dagli «access token» di tipo OAuth impiegati per la sicurezza delle connessioni.

REST o MCP: quando scegliere l’uno o l’altro

La scelta tra l’architettura REST e la connessione MCP dipende dall’utilizzatore finale e dal contesto d’uso dell’applicazione.

Le API REST sono la soluzione ideale quando il codice deve eseguire compiti deterministici e automatici: sincronizzazioni notturne nel CRM, widget di stima sul sito web, applicazioni mobile o servizi batch. Si autenticano tramite chiave API o client OAuth e operano senza l’intervento umano.

I server MCP (Model Context Protocol) si collegano invece agli ambienti di intelligenza artificiale come Claude, ChatGPT, Cursor, VS Code o Gemini CLI. Location Lookup, Area Insights, Comparables, AgentGraph AI e Claro AI dispongono ciascuno di un server MCP raggiungibile all’indirizzo https://platform.casafari.com/mcp/<prodotto>, con autenticazione OAuth 2.1 nel browser, come indicato nella guida su come collegare un server MCP CASAFARI (in inglese). Il repository GitHub casafari-mcp (in inglese) raccoglie il plugin per Claude Code, l’estensione per Gemini CLI ed esempi di codice per collegarsi ai server. L’utente o l’agente IA può porre domande in linguaggio naturale ed elaborare i dati in modo conversazionale.

Entrambe le modalità condividono lo stesso account, lo stesso plafond di token e il medesimo grafo immobiliare. Per verificare quali operazioni sono disponibili su entrambe le interfacce, è possibile consultare la tabella di parità fra REST e MCP (in inglese). Una regola pratica molto diffusa consiste nel prototipare un’idea in poche ore tramite MCP per poi ingegnerizzare il servizio finale con le API REST.

Da dove partire

Per iniziare a costruire la propria integrazione, il percorso più rapido prevede di registrare un account gratuito sulla console di CASAFARI, effettuare una prima chiamata a Location Lookup per identificare il codice di un quartiere a 0 token ed eseguire una successiva richiesta ad Area Insights. La documentazione completa e i diagrammi di flusso sono disponibili nell’indice dei casi d’uso della piattaforma.

Per le istituzioni finanziarie, i grandi gruppi immobiliari o i portali a elevato traffico che necessitano di soluzioni personalizzate o forniture di dati massive, la pagina Data Services per contratti su misura offre il supporto dedicato del team di ingegneria dei dati di CASAFARI.

Domande frequenti

Cosa si può fare con l’API immobiliare di CASAFARI?

L’API REST di CASAFARI consente di integrare la ricerca dei luoghi tramite Location Lookup, consultare i prezzi al metro quadro e i rendimenti locativi con Area Insights, alimentare motori di ricerca per app con Property Sourcing e individuare gli immobili con ribassi di prezzo ripetuti attorno a un punto con High Potential Seller Leads. Permette inoltre di generare valutazioni automatiche con Comparables & Valuation, analizzare locali commerciali in Spagna e Germania e terreni commerciali in Germania con Claro AI e monitorare i consumi tramite l’API Account. Tutti i servizi attingono a un grafo immobiliare deduplicato di 16 paesi, inclusa l’Italia.

Meglio REST o MCP per un’applicazione immobiliare?

La scelta dipende da chi o cosa avvia la richiesta. Le API REST sono da preferire quando il software deve eseguire operazioni automatiche, batch, job notturni o alimentare widget e applicazioni aziendali in modo deterministico. I server MCP sono ideali quando un utente o un agente IA interagisce in linguaggio naturale all’interno di ambienti come Claude, ChatGPT, Cursor o VS Code. Entrambe le interfacce condividono lo stesso account e lo stesso plafond di token, con dettagli analitici reperibili sulla pagina di parità su developers.casafari.com.

Quanto costa l’API immobiliare di CASAFARI?

La piattaforma offre un piano Free che include 1.000 token per 30 giorni senza richiesta di carta di credito. Il piano Agent costa 49 € al mese con fatturazione annuale oppure 70 € con fatturazione mese per mese, IVA esclusa, con la possibilità di acquistare crediti prepagati aggiuntivi o sottoscrivere piani Custom su misura. Le chiamate al servizio Location Lookup hanno un costo pari a 0 token su tutti i piani attivi, come riportato nella documentazione ufficiale di ottobre 2026.

Come si ottiene la chiave API di CASAFARI?

Per ottenere la chiave API occorre accedere alla console su platform.casafari.com, dove il primo accesso attiva automaticamente il piano Free. All’interno della dashboard di amministrazione è possibile generare una chiave API o un client OAuth da inserire come intestazione di autorizzazione Bearer nelle richieste HTTP. Per la connessione ai server MCP non occorre copiare la chiave: la procedura utilizza l’autenticazione tramite OAuth 2.1 direttamente nel browser.

L’API CASAFARI copre tutta l’Italia e anche i prezzi di compravendita reali?

Sì, l’Italia rientra tra i 16 paesi coperti dal property graph di CASAFARI, con annunci aggregati da portali, siti agenzia e classifieds ricondotti a una sola scheda unica per immobile con storico dei prezzi. Inoltre, per il mercato italiano le API integrano sia i dati dell’offerta attiva sia i prezzi reali di compravendita registrati presso le fonti ufficiali, consentendo valutazioni accurate sia per la compravendita sia per la locazione, come indicato negli approfondimenti della guida alla copertura dei paesi.