> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/installazione-e-manutenzione/open-city-crawler/come-funziona.md). # Come funziona ## Scoperta dei contenuti Quando un crawl parte su un sito, il crawler non conosce in anticipo tutte le pagine. Le scopre navigando. Parte dalla homepage, trova i link, li segue e costruisce progressivamente la mappa del sito. In parallelo usa anche la sitemap XML, se presente, per trovare più velocemente le pagine. Se la sitemap non è dichiarata nel file `robots.txt` ma è nota, può essere inserita manualmente nella configurazione del sito. Il crawler rispetta le istruzioni pubblicate nel file `robots.txt`. Se un'area del sito non è scansionabile, viene ignorata. All'avvio di un crawl è anche possibile sovrascrivere temporaneamente queste regole. Questa opzione è utile, ad esempio, per testare aree normalmente escluse. Tra i contenuti scoperti rientrano anche i PDF. Quando il crawler trova un link a un PDF, lo scarica e lo salva. Non analizza però il contenuto interno del file e non segue eventuali link presenti al suo interno. ## Fase di probe e ritmo adattivo All'inizio della scansione di un nuovo sito il crawler esegue una fase di calibrazione. Serve a capire quante pagine può processare in parallelo o in un lasso di tempo breve senza sovraccaricare il sito. Una volta individuato, questo valore viene salvato e riutilizzato come punto di partenza nei run successivi. Se necessario, è possibile forzare un nuovo *probe* dall'interfaccia. Durante la scansione, il crawler si adatta comunque continuamente al comportamento del sito. Se riceve segnali di rallentamento, come errori `429` o `503`, aumenta automaticamente il tempo di attesa tra una richiesta e l'altra. Se invece più *batch* di richieste consecutivi si chiudono senza problemi, riduce gradualmente questo ritardo. L'obiettivo è trovare il ritmo più veloce possibile che il sito sia in grado di sostenere. ## Aggiornamento dei contenuti Il crawler non riscansiona una pagina se non serve. Ogni pagina ha una finestra di validità che si allunga o si accorcia automaticamente in base alla sua storia. Le pagine che cambiano spesso vengono controllate più di frequente. Quelle stabili molto meno. Questo approccio concentra le risorse dove ci sono cambiamenti reali. Quando arriva il momento di ricontrollare una pagina, il crawler verifica prima se il contenuto è davvero cambiato. Usa le intestazioni HTTP standard e confronta il contenuto con quello salvato in precedenza. Solo se rileva una variazione reale, la pagina viene reindicizzata e la data di ultima modifica nella dashboard viene aggiornata. Questo significa che quel campo indica sempre un cambiamento effettivo del contenuto. Non indica semplicemente l'ultima visita del crawler (indicata dal campo *last visited*). ## Siti con contenuti JavaScript Alcuni siti caricano i contenuti principali tramite JavaScript. In questi casi il testo non è visibile nella versione HTML statica della pagina. Il crawler rileva automaticamente questa situazione confrontando le due versioni della pagina. Quando serve, usa un browser *headless* per ottenere la pagina così come la vedrebbe un utente reale. Il contenuto della pagina con JS caricato e il plain HTML vengono confrontati sia controllando la differenza di quantità di caratteri sia con un confronto attraverso AI. Questa classificazione viene memorizzata per ogni pagina. I run successivi non devono quindi ripetere ogni volta lo stesso confronto. ## Gestione degli errori Se una pagina smette di rispondere o restituisce errori ripetuti, il crawler non continua a tentare inutilmente. Dopo alcuni tentativi falliti consecutivi, la pagina viene messa in pausa automaticamente per alcuni giorni. Se il problema persiste anche dopo la pausa, il blocco si allunga progressivamente. Quando la pagina torna accessibile e risponde correttamente, il blocco viene rimosso in automatico e il contatore degli errori viene azzerato. ## Crawl giornalieri Ogni giorno alle 02:00 Windmill avvia automaticamente il crawl di tutti i siti disponibili per mantenerli aggiornati. Se un crawl è già in corso, il sistema blocca automaticamente i tentativi successivi sullo stesso sito. ## Opzioni manuali Puoi intervenire manualmente su singole pagine o su interi percorsi. Per esempio, puoi: * forzare una frequenza di riscansione diversa (di base il crawler non ricontrolla le pagine visitate nelle ultime 24 ore); * aggiungere un file `robots.txt` personalizzato per specificare un limite di velocità o bloccare la scansione di certi percorsi; * forzare un crawl da zero ignorando le regole per le pagine già visitate. Queste opzioni convivono con quelle automatiche e hanno precedenza su di esse. All'avvio di un crawl è anche possibile impostare un limite massimo di pagine da scansionare. Questa opzione è utile per test rapidi su siti molto grandi. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.opencityitalia.it/installazione-e-manutenzione/open-city-crawler/come-funziona.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.