Manuale di API Scraper Immobiliare

Cosa fa

• Interroga l’endpoint di ricerca indicato nel codice per Immobiliare.it usando la libreria requests.
• Imposta il contratto vendita quando tipo è esattamente vendita; per altri valori invia il codice contratto dell’affitto.
• Usa una mappatura di sei città per scegliere una regione: Milano, Roma, Torino, Napoli, Bologna e Firenze.
• Richiede al massimo cinque pagine, con 50 risultati richiesti per pagina, e attende un secondo dopo ogni pagina elaborata.
• Raccoglie per ciascun risultato id, titolo, prezzo, metri quadri, locali, zona, città, piano, URL, fonte e data di scraping.
• Crea un CSV UTF-8 quando viene raccolto almeno un annuncio e stampa statistiche di base nel terminale.
• Calcola totale annunci, prezzo medio, minimo e massimo, metri quadri medi e rapporto medio tra somma prezzi e somma metri quadri disponibili.

Cosa non fa

• Non esegue richieste a Idealista o Casa.it: il codice operativo chiama soltanto Immobiliare.it.
• Non filtra realmente per comune: il parametro città serve a selezionare una regione nella mappatura e viene riportato nel CSV.
• Non genera un file JSON, né i nomi annunci.csv e annunci.json indicati nel README.
• Non include codice per esportare o autenticarsi con Google Sheets.
• Non esegue ricerche storiche, deduplicazione, pianificazione automatica, notifiche o valutazioni immobiliari.
• Non garantisce disponibilità dell’endpoint, completezza, aggiornamento, accuratezza o liceità del riutilizzo dei dati.

Requisiti

• Archivio estratto: Estrai il file ZIP e conserva insieme immobiliare-scraper.py e requirements.txt. I README sono guide di consultazione.
• Python 3.9 o successivo: Lo script usa annotazioni come list[Annuncio], compatibili con Python 3.9 e versioni successive. La verifica del pacchetto è stata effettuata con Python 3.12.3.
• Terminale e ambiente virtuale: Servono per installare la dipendenza senza mescolarla con altri progetti Python.
• Connessione Internet: È necessaria solo quando esegui lo script, perché esso invia richieste HTTPS al servizio indicato nel codice.
• Dipendenza Python requests: È l’unica dipendenza dichiarata, nella versione 2.31 o successiva; il comando di installazione la installa con le sue dipendenze tecniche.
• Accesso consentito al portale e base giuridica per l’uso dei dati: Prima dell’uso verifica termini del sito, robots.txt ove applicabile, limiti di frequenza, eventuali autorizzazioni e obblighi GDPR. Non è richiesto alcun token, account o chiave API dal pacchetto.
• Editor di testo: Ti serve per modificare la chiamata scraper.search nella sezione finale di immobiliare-scraper.py.

Installazione passo passo

1. 1. Estrai il pacchetto. Decomprimi il file ZIP in una cartella di lavoro a tua scelta. Verifica che vi siano immobiliare-scraper.py, requirements.txt, README.md e README.en.md nella stessa cartella.
2. 2. Leggi la documentazione consegnata. README.md è la guida originale in italiano. README.en.md è una traduzione informativa inglese e precisa che l’originale italiano resta autorevole. Leggi anche le condizioni del portale che intendi interrogare prima di procedere.
3. 3. Apri un terminale nella cartella estratta. Nel terminale spostati nella cartella che contiene lo script. Il comando seguente mostra il contenuto atteso. Sostituisci il percorso con la tua cartella reale.
4. 4. Controlla Python e crea un ambiente isolato. Verifica che Python sia disponibile e crea un ambiente virtuale chiamato .venv. Se il comando python non funziona sul tuo sistema, usa il comando con cui normalmente avvii Python, purché sia Python 3.9 o successivo.
5. 5. Attiva l’ambiente virtuale. Su macOS o Linux attiva l’ambiente prima di installare la dipendenza. Il prompt del terminale di solito mostra il nome .venv quando l’attivazione è avvenuta.
6. 6. Installa la dipendenza dichiarata. Installa esattamente ciò che è elencato nel file requirements.txt. L’installazione richiede una connessione Internet e può usare un archivio di pacchetti Python configurato sul tuo sistema.
7. 7. Apri la configurazione iniziale dello script. Apri immobiliare-scraper.py e trova il blocco finale che inizia con if __name__ == "__main__". La riga scraper.search contiene i quattro parametri da adattare: città, tipo, prezzo massimo e metri quadri minimi.
8. 8. Imposta filtri realistici e controlla la mappatura. Per la ricerca in vendita usa vendita; per l’affitto usa affitto. Le città con mappatura esplicita sono milano, roma, torino, napoli, bologna e firenze, senza distinzione tra maiuscole e minuscole. Per qualunque altro testo lo script usa lombardia come regione e salva comunque il testo scelto nella colonna città: non presumere quindi un filtro comunale.
9. 9. Esegui lo script una sola volta per il primo controllo. Dopo aver verificato autorizzazioni, termini, robots.txt ove applicabile e limiti di richiesta del portale, esegui lo script dalla stessa cartella. Non chiudere il terminale finché non vengono visualizzati il conteggio e, se presenti risultati, le statistiche.
10. 10. Controlla l’output effettivo. Se lo script trova almeno un annuncio, crea un CSV con nome immobiliare_milano_AAAAMMGG.csv, anche se hai cambiato città. Aprilo con un foglio di calcolo o un editor compatibile con UTF-8. Se il conteggio è zero, il codice non crea alcun CSV. Non aspettarti un file JSON o una sincronizzazione Google Sheets: non sono implementati in questa consegna.

Uso quotidiano

Rivedi filtri e autorizzazioni prima di ogni esecuzione

Controlla città, tipo, prezzo massimo e metri quadri minimi nella chiamata finale. Conferma nuovamente che il tuo uso sia consentito dal portale e proporzionato alle sue regole.

Avvia dallo stesso percorso dello script

Esegui il comando nella cartella contenente immobiliare-scraper.py. In questo modo il CSV, se prodotto, verrà creato nella cartella prevista e potrai individuarlo facilmente.

Osserva il terminale

All’avvio compare il messaggio relativo a Milano e vendita, che è un testo fisso e non si aggiorna se modifichi i filtri. Usa invece il CSV e i parametri che hai impostato per interpretare la sessione.

Verifica il CSV prima di analizzarlo

Controlla intestazioni, URL, zona, città e campi mancanti. La data di scraping indica quando lo script ha creato quella riga, non la data di pubblicazione dell’annuncio.

Interpreta la sintesi con cautela

La sintesi a terminale è calcolata soltanto sui record raccolti nell’esecuzione. Confronta sempre le singole righe, i filtri applicati e gli eventuali valori mancanti prima di usarla in un’analisi.

Conserva separatamente le esecuzioni

Il nome CSV contiene la data ma non l’ora; più esecuzioni nello stesso giorno con lo stesso prefisso possono sovrascrivere il file. Rinomina o archivia il CSV dopo averlo controllato.

Casi pratici

Esame preliminare di annunci in vendita in Lombardia

Una persona che studia il mercato immobiliare vuole leggere in un foglio di calcolo gli annunci restituiti con una soglia di prezzo e superficie.

1. Lascia citta impostata su milano, comprendendo che la richiesta usa la regione Lombardia.
2. Imposta tipo su vendita e scegli soglie positive per prezzo_max e mq_min.
3. Esegui lo script soltanto se il portale consente il tuo uso e con frequenza responsabile.
4. Apri il CSV generato e confronta zona, prezzo, superficie e URL delle singole righe.

Ottieni un CSV locale degli annunci restituiti in quella esecuzione, utile per un’analisi esplorativa manuale.

Rassegna di annunci in affitto associata a Roma

Un piccolo studio vuole esaminare un insieme di annunci in affitto associati al valore roma della mappatura del codice, senza considerarlo un filtro preciso per il comune.

1. Sostituisci il primo argomento con roma e il secondo con affitto.
2. Scegli soglie coerenti con il controllo che vuoi fare.
3. Aggiorna il prefisso di output se desideri che il nome del CSV indichi Roma.
4. Esegui lo script e verifica le zone e gli URL del file prodotto.

Ottieni dati da controllare manualmente, con il valore città roma riportato nel CSV e la richiesta impostata sulla regione Lazio.

Confronto manuale tra due esecuzioni

Un analista desidera confrontare in modo qualitativo i risultati di due filtri diversi, mantenendo traccia dei file prodotti.

1. Esegui una prima ricerca consentita con una combinazione di filtri.
2. Rinomina il CSV risultante includendo data, ora e filtri in un nome scelto da te.
3. Modifica una sola soglia o il tipo di contratto nella chiamata scraper.search.
4. Esegui nuovamente nel rispetto delle regole del portale e confronta le colonne dei due CSV.

Ottieni due esportazioni locali con contesto documentato, da valutare senza attribuire differenze a dati completi o definitivi.

Apprendimento del flusso Python verso CSV

Chi sta imparando Python vuole osservare un esempio semplice di dataclass, richiesta HTTP, trasformazione dei dati ed esportazione CSV.

1. Leggi la dataclass Annuncio e le sue undici proprietà.
2. Esamina il metodo search e i parametri della richiesta senza eseguirlo.
3. Osserva come to_csv usa asdict e csv.DictWriter.
4. Esegui solo se autorizzato, quindi confronta le intestazioni CSV con i campi della dataclass.

Ottieni un esempio concreto da studiare e, se l’esecuzione è consentita, un CSV locale che mostra la struttura effettivamente prodotta.

Consigli

• Inizia con i valori già presenti nel codice per verificare installazione e formato dell’output prima di cambiare più elementi insieme.
• Usa solo minuscole per le città della mappatura, anche se il codice converte comunque il valore per il confronto.
• Tratta un valore di città fuori dalle sei previste come una ricerca in Lombardia finché non hai modificato e compreso la funzione _get_region_code.
• Non dedurre che il CSV contenga soltanto annunci di un comune: ispeziona l’URL, la zona e le singole righe.
• Apri il CSV in UTF-8 per preservare caratteri italiani nei titoli e nelle zone.
• Non aumentare arbitrariamente pagine, risultati per pagina o frequenza: il codice ha già una pausa di un secondo, ma devi comunque rispettare termini, robots.txt e rate limit del servizio.
• Se cambi città, modifica anche il prefisso immobiliare_milano_ del nome file per evitare etichette fuorvianti.
• Archivia i CSV con una nota sui filtri usati, perché nel nome del file non sono memorizzati tipo, soglie o orario di esecuzione.
• Considera prezzo, superficie, locali e piano come campi potenzialmente assenti o formattati dal servizio; verifica i record prima di calcoli successivi.
• Non condividere o pubblicare dati che possano contenere dati personali senza una base giuridica e senza aver valutato gli obblighi applicabili.

Risoluzione dei problemi

Il comando python non viene trovato o mostra una versione troppo vecchia.

Python non è installato, non è nel PATH oppure è precedente alla sintassi list[Annuncio] usata dallo script. Installa o seleziona Python 3.9 o successivo secondo la procedura del tuo sistema, poi ripeti il controllo della versione e crea nuovamente l’ambiente virtuale.

Compare ModuleNotFoundError: No module named requests.

La dipendenza non è stata installata nell’interprete con cui stai avviando lo script, oppure l’ambiente virtuale non è attivo. Attiva .venv e usa pip install -r requirements.txt. Avvia poi con python dello stesso ambiente; non modificare requirements.txt se non sai perché.

L’esecuzione termina con un errore di connessione, timeout o certificato.

Lo script effettua una richiesta HTTPS con timeout di 10 secondi e non gestisce eccezioni di rete nel codice consegnato. Controlla connessione, proxy e configurazione certificati del tuo ambiente. Verifica inoltre se il portale consente il tuo accesso; non aggirare blocchi, rate limit o protezioni.

Il terminale mostra Trovati 0 annunci e non viene creato alcun CSV.

L’endpoint ha restituito una risposta non positiva, nessun risultato nelle pagine lette oppure filtri non compatibili con i dati restituiti. Il codice chiama to_csv soltanto se la lista non è vuota. Ricontrolla termini e autorizzazioni, poi rivedi i quattro filtri senza tentare di aumentare aggressivamente le richieste. Ricorda che la città è tradotta in regione e che un valore non mappato usa Lombardia.

Il CSV ha nel nome Milano anche se ho configurato un’altra città.

Il prefisso immobiliare_milano_ è scritto letteralmente nella chiamata to_csv del blocco finale. Modifica solo quel prefisso in un’etichetta coerente prima dell’esecuzione, oppure rinomina il file dopo averlo creato. Questa modifica non cambia la ricerca.

Cerco un file JSON ma non lo trovo.

Il README menziona JSON, ma il codice effettivo include soltanto il metodo to_csv e chiama soltanto l’esportazione CSV. Usa il CSV prodotto. Non presumere che annunci.json venga creato e non presentare una conversione esterna come funzionalità inclusa nel pacchetto.

Non vedo dati su Idealista, Casa.it o Google Sheets.

Il commento iniziale e il README citano queste possibilità, ma il flusso eseguibile consegnato usa soltanto l’URL base di Immobiliare.it e non contiene codice Google Sheets. Limita le aspettative alla raccolta da Immobiliare.it e al CSV locale. Eventuali integrazioni aggiuntive richiedono sviluppo separato e il rispetto delle regole dei servizi coinvolti.

Il messaggio iniziale continua a dire Milano — vendita dopo aver cambiato i parametri.

La stringa di stampa all’avvio è fissa nel blocco finale e non usa i valori configurati. Non usare quel messaggio come conferma dei filtri. Controlla la riga scraper.search, poi verifica città, zona e URL nel CSV ottenuto.

Le statistiche sembrano poco rappresentative o alcuni valori mancano.

Le statistiche sono calcolate soltanto sui campi prezzo e mq disponibili nei risultati raccolti; non sono una valutazione immobiliare e non verificano i dati alla fonte. Ispeziona il CSV riga per riga, annota i valori mancanti e usa le statistiche solo come riepilogo tecnico della raccolta, non come base unica per decisioni economiche.

Limiti da conoscere

• Lo script è legato a un endpoint esterno non controllato dal pacchetto; cambiamenti nel sito, risposta non 200, formati inattesi o limitazioni di accesso possono interromperlo.
• Il filtro città non è un filtro comunale: è una mappatura a regione per sei nomi; altri nomi ricadono in Lombardia.
• Vengono richieste al massimo cinque pagine e 50 risultati per pagina, ma il numero effettivo dipende dalla risposta esterna e dai filtri.
• I dati estratti possono essere incompleti, errati, duplicati, rimossi o non aggiornati. Verifica sempre l’annuncio originale tramite URL.
• Rispetta termini d’uso, robots.txt ove applicabile, rate limit, diritto sui database, GDPR e ogni altra regola applicabile. Non usare il programma per aggirare controlli o raccogliere dati personali senza base giuridica.
• Prezzi e statistiche sono informazioni tecniche raccolte dallo script, non consulenza immobiliare, finanziaria, legale o fiscale.
• Il pacchetto non contiene chiavi API, credenziali, invio email, notifiche, pianificazione, JSON o Google Sheets.

Domande frequenti

Devo creare un account o inserire una chiave API?

No. Nei file consegnati non sono presenti né richiesti account, token, password o chiavi API. Questo non sostituisce l’obbligo di verificare se il portale consente il tipo di accesso che intendi effettuare.

Quali siti vengono interrogati davvero?

Il codice operativo esegue richieste soltanto all’URL base di Immobiliare.it. Non ci sono chiamate operative a Idealista, Casa.it o Google Sheets.

Lo script cerca davvero nel comune scelto?

No in modo dimostrabile dal codice. Per sei nomi di città seleziona una regione; per gli altri seleziona Lombardia. Il testo della città viene anche scritto nel CSV, ma non è passato come filtro comunale nella richiesta.

Perché non ottengo annunci.json?

Perché lo script consegnato non implementa un’esportazione JSON. La menzione nel README non corrisponde al comportamento del codice eseguibile, che salva solo CSV quando trova risultati.

Dove trovo il CSV e come si chiama?

Viene creato nella cartella da cui esegui lo script, soltanto se la raccolta contiene almeno un annuncio. Il nome segue immobiliare_milano_AAAAMMGG.csv e il prefisso resta Milano finché non lo modifichi nel codice.

Quanti annunci raccoglie?

Il codice prova a leggere da pagina 1 a pagina 5 e richiede 50 risultati per pagina. Può fermarsi prima se una risposta non è 200 o se non trova risultati; il numero ottenuto non è garantito.

Posso usare le statistiche per decidere un acquisto o un investimento?

No. Sono semplici calcoli sui dati disponibili nella singola esecuzione e non sostituiscono verifiche sugli annunci né consulenza professionale. Valuta fonti, campi mancanti e rischi prima di ogni decisione.