Location Lookup via MCP e REST: come un agente IA risolve un luogo prima di chiedere dati immobiliari
Location Lookup di CASAFARI è lo strumento di geocodifica che trasforma il nome di un comune o quartiere, o un CAP, in un identificatore univoco denominato location_id. Disponibile a 0 token tramite il server MCP https://platform.casafari.com/mcp/locations (strumento locations_search) o via API REST, costituisce il passaggio preliminare gratuito indispensabile prima di interrogare i dati di Area Insights, Comparables o Property Sourcing.
Quando un utente chiede al proprio assistente IA le valutazioni di mercato per un appartamento a Castelnuovo, il modello linguistico si trova di fronte a una trappola geografica. Senza un riferimento univoco, l’agente rischia di recuperare i valori di Castelnuovo Berardenga anziché quelli di Castelnuovo del Garda, spendendo token per risposte errate. Il flusso corretto prevede un passaggio preventivo: interrogare il dizionario geografico, ottenere il location_id e passare tale codice agli strumenti di analisi.
Che cos’è Location Lookup e perché costa 0 token
Location Lookup rappresenta la porta d’accesso geografica al property graph di CASAFARI, che raccoglie e deduplica gli immobili residenziali e commerciali in 16 paesi (Stati Uniti: ingresso in corso, Stati selezionati, solo immobili commerciali, con Claro AI). L’Italia è coperta da questa struttura dati.
Lo strumento MCP si chiama locations_search ed è ospitato sul server https://platform.casafari.com/mcp/locations. La sua funzione primaria è abbinare qualsiasi stringa di testo fornita dall’utente a un’entità geografica riconosciuta, restituendo il relativo location_id insieme alla tipologia del luogo (comune, quartiere o suddivisione amministrativa).
Le ricerche effettuate con Location Lookup costano 0 token su qualsiasi piano. Come indicato nelle domande frequenti su piani e token (aggiornate al 23 ottobre 2026), l’accesso iniziale prevede un piano Free da 1.000 token validi per 30 giorni senza inserire la carta di credito. Gli abbonamenti a pagamento per l’accesso esteso, come il piano Agent a 49 EUR al mese con fatturazione annuale o 70 EUR al mese con fatturazione mensile (IVA esclusa), applicano i token unicamente alle chiamate di analisi e valutazione. La risoluzione geografica è gratuita poiché una chiamata a pagamento eseguita su un luogo errato genererebbe un’analisi priva di valore.
Perché in Italia il nome di un luogo non basta
La geografia amministrativa italiana presenta un’elevata densità e frequenti sovrapposizioni nominali. Secondo i dati ISTAT aggiornati al 1° gennaio 2026, in Italia si contano 7.895 comuni (i codici delle unità amministrative ISTAT 2026). Tra questi figurano decine di omonimie o quasi-omonimie: dai diversi comuni denominati San Giorgio o Santa Maria, fino alle molteplici declinazioni di Castelnuovo presenti in regioni differenti.
Nelle grandi metropoli la complessità aumenta. I confini postali non sempre rispecchiano la reale percezione del mercato immobiliare. Per esempio, il Piano di Governo del Territorio definisce per la città di Milano 88 Nuclei di Identità Locale (NIL), consultabili sulla mappa dei NIL del Comune di Milano. Un quartiere storico come Porta Romana o un’area direzionale come Porta Nuova corrispondono a specifiche dinamiche di prezzo che un modello LLM non può dedurre autonomamente da un testo generico. Consultare la guida ai quartieri di Milano evidenzia come i micro-mercati urbani richiedano perimetri precisi.
Un modello linguistico privo di geocodifica tende a completare l’informazione ipotizzando le coordinate. Al contrario, un location_id garantisce una corrispondenza deterministica. Qualora un toponimo risulti insolito o non venga individuato al primo tentativo, è possibile consultare le indicazioni del centro assistenza su cosa fare se una località non compare.
Come funziona locations_search via MCP
Per consentire a un agente IA di risolvere i nomi di luogo, si collega il server MCP di CASAFARI come connettore personalizzato all’interno dell’ambiente di lavoro scelto. La procedura è descritta nella guida alla connessione dei server MCP CASAFARI (ottobre 2026).
I client supportati includono Claude (su claude.ai, applicazione Desktop e mobile), ChatGPT (in Developer mode), Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI e la maggior parte degli ambienti di sviluppo compatibili con lo standard MCP. La connessione utilizza il trasporto Streamable HTTP e l’autenticazione OAuth 2.1 via browser, senza la necessità di copiare manualmente chiavi segrete. È opportuno distinguere l’access token di OAuth, che rappresenta la credenziale di autenticazione della sessione, dai token di consumo che misurano l’utilizzo dei servizi a pagamento.
Quando un utente chiede «Qual è il prezzo medio al metro quadro a Porta Romana, Milano?», l’agente esegue la seguente sequenza:
- Chiama lo strumento
locations_searchsul serverhttps://platform.casafari.com/mcp/locationscon la queryPorta Romana, Milano. - Riceve la risposta contenente il
location_idunivoco corrispondente al quartiere (NIL) di Porta Romana. - Invia il
location_idottenuto agli strumenti dedicati, come Area Insights, per estrarre le metriche aggiornate di mercato; Comparables lavora invece su un punto, un indirizzo o un riferimento catastale.
Questa architettura integra perfettamente la pagina di CASAFARI MCP, permettendo agli agenti conversazionali di operare con dati rigorosi.
La stessa ricerca in REST
Per gli sviluppatori che integrano i dati immobiliari in applicazioni tradizionali, backend web o pipeline ETL, il servizio di geocodifica è accessibile tramite endpoint REST dedicati. Come illustrato nel repository pubblico casafari-mcp, l’interrogazione si effettua con una richiesta HTTP GET:
GET https://platform.casafari.com/v1/locations/search?query=Bologna
La chiamata richiede l’intestazione Authorization: Bearer <chiave API>, con la chiave creata all’interno della console di gestione. Gli identificatori restituiti dalle API REST sono identici a quelli erogati dal server MCP. Un location_id identificato tramite API REST può essere riutilizzato in sessioni MCP e viceversa. Per una visione d’insieme dell’infrastruttura di integrazione è possibile consultare la panoramica su le API di dati immobiliari CASAFARI e l’articolo di approfondimento che spiega che cos’è un’API immobiliare.
Tre regole per un agente che lavora con i luoghi
Per garantire la massima precisione nelle analisi geografiche e ottimizzare i consumi dell’account, è consigliabile strutturare le istruzioni dell’agente IA attorno a tre regole fondamentali:
- Risoluzione preventiva obbligatoria: non effettuare chiamate a strumenti di analisi a pagamento (Area Insights, Comparables, Property Sourcing) utilizzando testo libero. Risolvere sempre prima la stringa geografica tramite Location Lookup a 0 token.
- Gestione delle ambiguità: quando la ricerca restituisce più candidati di pari livello (ad esempio due comuni con lo stesso nome in province diverse), configurare l’agente affinché chieda conferma all’utente prima di procedere.
- Persistenza del contesto: salvare il
location_idselezionato all’interno della memoria di sessione. Le successive interrogazioni sullo stesso luogo dovranno riutilizzare l’identificatore già ottenuto, evitando chiamate ridondanti.
Prima di richiedere analisi di prezzo, valutazioni o trend di mercato, è possibile accedere a platform.casafari.com e creare l’account Free per testare immediatamente la risoluzione dei luoghi tramite MCP o API REST.
Domande frequenti
Che cos’è Location Lookup di CASAFARI?
Location Lookup di CASAFARI è il dizionario geografico che trasforma un nome di comune, quartiere o indirizzo in un location_id univoco. È disponibile come server MCP all’indirizzo https://platform.casafari.com/mcp/locations tramite lo strumento locations_search, oppure come endpoint REST. Area Insights e Property Sourcing richiedono questo identificatore in ingresso per restituire dati precisi.
Quanto costa una ricerca con Location Lookup?
Le ricerche con Location Lookup costano 0 token su qualsiasi piano. Il piano Free mette a disposizione 1.000 token per 30 giorni senza richiedere la carta di credito, mentre il piano Agent è disponibile a 49 EUR al mese con fatturazione annuale o 70 EUR al mese con fatturazione mensile (IVA esclusa). Il consumo di token si applica unicamente alle interrogazioni dei prodotti di analisi.
Come collego Claude o ChatGPT al server MCP di CASAFARI?
Il collegamento avviene inserendo l’URL https://platform.casafari.com/mcp/locations come connettore personalizzato su Claude (claude.ai, applicazione Desktop e mobile) o su ChatGPT in Developer mode. Il servizio utilizza il trasporto Streamable HTTP e l’autenticazione OAuth 2.1 via browser, consentendo di creare l’account Free al primo accesso senza copiare chiavi manuali. La configurazione è supportata anche su Cursor, VS Code e Claude Code.
Perché un agente IA deve risolvere il luogo prima di chiedere i dati?
Strumenti di analisi come Area Insights e Property Sourcing accettano perimetri geografici espressi tramite location_id, cerchi o poligoni, e non tramite testo libero. In Italia la geocodifica preventiva è indispensabile a causa della presenza di 7.895 comuni (dati ISTAT, gennaio 2026) con frequenti omonimie e di suddivisioni urbane complesse, come gli 88 NIL di Milano. Risolvere l’identificatore prima della chiamata evita di consumare token per dati riferiti al comune o quartiere sbagliato.
Posso usare Location Lookup anche via API REST, senza MCP?
Sì, inviando una richiesta GET all’endpoint https://platform.casafari.com/v1/locations/search specificando il parametro query con il nome del luogo o il CAP. La chiamata richiede un’intestazione Authorization Bearer con la chiave API generata nella console di platform.casafari.com. Gli identificatori location_id restituiti via REST sono identici a quelli forniti dal server MCP.