Formato xml per la sottomissione degli annunci

versione 1.06 – novembre 2021

CaasaBot supporta il seguente formato xml (simile alle sitemap) per la sottomissione automatica di annunci. Di seguito è riportato un esempio di sitemap per caasa che contiene 1 solo annuncio:
<?xml version="1.0" encoding="utf-8"?>
<listings>
        <listing>
             <contract>FOR-SALE</contract>
             <mls>CAA0FA50B</mls>
             <source>http://www.caasa.it/annunci/prova.html</source>
             <title><![CDATA[Quadrivano luminoso pressi via Vesalio]]></title>
             <description><![CDATA[In via Efisio Melis (adiacenze via Vesalio), luminoso quadrivano al primo piano di un piccolo condominio ristrutturato di recente.
             I doppi servizi e la cucina abitabile, oltre alla dotazione di pompe di calore in ogni stanza, lo rendono estremamente confortevole anche per una piccala famiglia.
             L'appartamento viene ceduto parzialmente ammobiliato e si presta ad essere abitato da subito. Mutuabile al 100%. Posto auto scoperto.
             ]]></description>
             <misc><![CDATA[giardino condominiale]]></misc>
             <location>
                       <city province="CA">Cagliari</city>
                       <address>via Efisio Melis, Pirri</address>
                       <geopos>45.366628;9.5422423</geopos>
             </location>
             <area>100</area>
             <garden-area>0</garden-area>
             <price>290000</price>
             <floor>primo</floor>
             <bathrooms>2</bathrooms>
             <parking>1</parking>
             <ACE ipe="48.2">B</ACE>
             <pubblication>2016-11-27</pubblication>
             <update>2017-02-13</update>
             <build-date>1982</build-date>
             <contact>
                      <id>REORA065</id>
                      <name><![CDATA[LAQUALUNQUE IMMOBILIARE]]></name>
                      <url hide="true">http://www.laqualunque-immobiliare.com</url>
                      <address>Piazza Italia, 121</address>
                      <postal-code>09134</postal-code>
                      <city province="CA">Cagliari</city>
                      <email>pilu@laqualunque-immobiliare.com</email>
                      <image title="Potremmo fregarti, ma non lo faremo!" height="60" width="180">http://www.laqualunque-immobiliare.com/logo.jpg</image>
                      <tel>+3934702826735,+39070000000</tel>
             </contact>
             <images>
                     <image title="vista da via Iannone" height="300" width="400">http://images.caasa.it/624526.jpg</image>
                     <image title="planimetria" height="300" width="400" type="layout">http://images.caasa.it/624527.jpg</image>
                     <image height="300" width="400">http://images.caasa.it/624528.jpg</image>
                     <image height="300" width="400">http://images.caasa.it/624529.jpg</image>
                     <image height="300" width="400">http://images.caasa.it/624530.jpg</image>
             </images>
             <videos>
                     <video title="una visita in anteprima">http://www.youtube.com/watch?v=lTkKYIjbRyo</video>
             </videos>
        </listing>
</listings>
  • Il campo contract è obbligatorio e può assumere i valori “FOR-SALE” o “FOR-RENT“.
  • Il campo mls è facoltativo e consente di indicare il codice univoco dell’annuncio in un contesto di Multiple Listing Service. Può essere indicato anche nella descrizione o in feed in altri formati.
  • Il campo source è obbligatorio e deve contenere l’url (completo di http://) della sorgente dell’annuncio. CaasaBot potrebbe scaricare tale url sia per estrarre ulteriori informazioni che per verificare la corrispondenza di quelle contenuta nella sitemap con quelle “reali”.
  • Il campo title è obbligatorio e NON deve essere vuoto. Non può contenere testo formattato in html.
  • Il campo description è obbligatorio e NON deve essere vuoto. Non può contenere testo formattato in html. Anche se Caasa mostra agli utenti solo una parte della descrizione, nella sitemap dev’essere presente in modo completo, perché viene utilizzata da CaasaBot per estrarre keyword e altre informazioni sull’annuncio. Inoltre un annuncio con una descrizione ridotta ha un rank basso.
  • Il campo misc è facoltativo e contiene ulteriori informazioni sull’immobile che non siano già contenute nel titolo o nella descrizione. Viene utilizzato da CaasaBot per estrarre ulteriori informazioni, ma è considerato meno “affidabile” rispetto alla descrizione.
  • Il campo location è obbligatorio e racchiude le informazioni riguardo la localizzazione dell’immobile:
    • il campo city è obbligatorio e rappresenta il nome del comune in cui è ubicato l’immobile. L’attributo province è opzionale e rappresenta il codice di 2 lettere associato alla provincia (ad es. MI per Milano). Per quanto opzionale, l’indicazione della provincia è fortemente consigliata: nel caso in cui non venga indicata è obbligatorio usare per la città il nome esatto del comune, come fornito dall’ISTAT.
    • il campo address è facoltativo e rappresenta ulterioriori informazioni sulla localizzazione dell’immobile; può contenere un indirizzo (nome di una via, di una piazza, etc) o un quartiere/zona o una frazione/località. Se disponibili più informazioni geografiche (ad esempio via e quartiere), è possibile (anzi fortemente consigliato) indicarle tutte, separandole con virgole o trattini. Un annuncio con una precisa collocazione geografica ha un rank migliore e ottiene un miglior posizionamento tra i risultati di ricerca.
    • il campo geopos è facoltativo e indica latitudine e longitudine (in quest’ordine, separate da un punto e virgola e con i decimali separati da un punto). Un annuncio con l’indicazione della posizione geografica ha un rank migliorato, ma se l’indicazione è sbagliata (troppo lontana dalla città o dalla via/quartiere indicata) viene considerato “sospetto” e il suo rank è fortemente penalizzato.
  • Il campo area è facoltativo e indica il numero di mq dell’immobile. Non sono ammessi decimali o valori negativi.
  • Il campo garden-area è facoltativo e può essere indicato solo se il campo area è valorizzato e se l’immobile dispone di un giardino privato . In tal caso indica il numero di mq del giardino. Non sono ammessi decimali o valori negativi.
  • Il campo price è facoltativo e indica il prezzo di vendita o il prezzo dell’affitto mensile dell’immobile. Non sono ammessi decimali o valori negativi. In caso di affitto è possibile indicare il periodo temporale cui si riferisce la locazione con l’attributo opzionale period che può assumere i valori: “monthly” (default), “weekly”, “daily”, “yearly”.
  • Il campo floor è facoltativo e indica il piano al quale è ubicato l’immobile e può essere un numero (0 indica il piano terra) o anche ‘terra’, ‘primo’ o ‘secondo’.
  • Il campo bathrooms è facoltativo ed è un numero intero non negativo che indica il numero di bagni (anche di servizio) nell’immobile.
  • Il campo parking è facoltativo ed è un numero intero non negativo che indica il numero di posti auto (coperti o scoperti) nella disponibilità dell’immobile.
  • Il campo ACE permette d’indicare la classe di efficienza energetica e l’ Indice di Prestazione Energetica dell’immobile, come risulta dall’Attestato di Certificazione Energetica (ACE). E’ facoltativo, visto che Caasa non pubblica direttamente gli annunci e rimanda al sito originale. I valori ammessi sono (“A+”, “A”, “B”, “C”, “D”, “E”, “F” e “G”). Può essere indicato anche l’IPE, tramite l’apposito attributo ipe (facoltativo) che dev’essere indicato in kwh/m².
  • Il campo pubblication è facoltativo è indica la data di prima pubblicazione dell’annuncio. Deve essere formattato con AAAA-MM-GG ovvero con 4 cifre per l’anno, un trattino, 2 cifre per il mese, un trattino, 2 cifre per il giorno.
  • Il campo update è facoltativo ed indica la data di ultimo aggiornamento dell’annuncio. Deve essere formattato con AAAA-MM-GG ovvero con 4 cifre per l’anno, un trattino, 2 cifre per il mese, un trattino, 2 cifre per il giorno.
  • Il campo build-date è facoltativo ed indica la data di costruzione dell’immobile. Deve essere formattato con AAAA ovvero con 4 cifre per l’anno.
  • Il campo contact è facoltativo e contiene le informazioni relative a chi propone l’immobile. Anche se tali informazioni sono opzionali e alcune NON vengono mai mostrate agli utenti, concorrono alla determinazione del rank: un annuncio con dettagliate informazioni sul contact ha un rank più alto.
    • Il campo id è facoltativo e contiene il nome il codice univoco dell’agenzia che propone in vendita l’immobile. Può essere indicato da solo (e i valori vengono ricavati dai nostri db), anche nella descrizione o in feed di altri formati.
    • Il campo name è obbligatorio (sempre che esista il campo contact) e contiene il nome di chi propone l’immobile.
    • Il campo url è facoltativo ed indica l’indirizzo (comprensivo di http://) del sito di chi propone l’immobile. L’attributo facoltativo hide indica se tale campo deve o meno essere occultato. Di default hide è “true” (non verrà mostrato).
    • Il campo email è facoltativo e indica l’email del contatto proponente l’immobile. Tale email NON verrà mai mostrata da Caasa agli utenti, ma la sua presenza partecipa alla determinazione del rank.
    • Il campo address è facoltativo ed indica l’indirizzo della sede del proponente l’immobile (tipicamente la sede dell’agenzia immobiliare). L’attributo facoltativo hide indica se tale campo deve o meno essere occultato. Di default hide è “true” (non verrà mostrato).
    • Il campo postal-code è facoltativo e permette d’indicare il CAP della sede del proponente l’immobile (tipicamente la sede dell’agenzia immobiliare).
    • Il campo city è facoltativo e permette d’indicare la città in cui ha sede il proponente l’immobile (tipicamente la sede dell’agenzia immobiliare).
    • Il campo tel è facoltativo e permette d’indicare uno o più (separati da virgole) contatti telefonici del proponente l’immobile. L’attributo facoltativo hide indica se tale campo deve o meno essere occultato. Di default hide è “true” (non verrà mostrato).
    • Il campo image è facoltativo ed è l’url (comprensivo di http://) di un’immagine da utilizzare come logo per il proponente l’immobile. Tale logo verrà mostrato con una dimensione di 90×25;  se non fosse disponibile un’immagine di dimensioni adatte alla visualizzazione in un tale formato, è possibile utilizzare gli attributi facoltativi height e width per indicare le dimensioni attuali dell’immagine (utilizzabili per uno scaling ottimizzato). L’attributo facoltativo title, sarà utilizzato nel campo title dell’immagine.
  • Il campo opzionale images contiene l’elenco delle immagini disponibili per l’annuncio. Caasa mostra al momento una sola immagine per annuncio, ma un annuncio con più immagini ha un rank migliore. Al contrario un annuncio senza immagini ha un rank molto basso.
    • il singolo campo image è l’url (comprensivo di https://) di un’immagine relativa all’immobile. Tale immagine verrà mostrata con una dimensione di 150×113;  se non fosse disponibile un’immagine di dimensioni adatte alla visualizzazione in un tale formato, è possibile utilizzare gli attributi height e width per indicare le dimensioni attuali dell’immagine (utilizzabili per uno scaling ottimizzato). L’attributo facoltativo priority permette di indicare una priorità tra le immagini (da 0 a 99) e quindi di scegliere quale tra quelle disponibili verrà visualizzata (di default la prima). L’attributo facoltativo title, sarà utilizzato nel campo title dell’immagine. L’attributo facoltativo type, permette di specificare di che tipo d’immagine si tratta: al momento è supportato il solo valore “layout” ad indicare che si tratta di una planimetria.
  • Il campo opzionale videos contiene l’elenco di video disponibili per l’annuncio. Caasa mostra al momento al più un solo video per annuncio, ma un annuncio con uno o più video ha un rank migliore.
    • il singolo campo video è l’url (comprensivo di https://) di un video. Al momento sono supportati solo video presenti su youtube, nella forma quindi http://www.youtube.com/watch?v=videoID. L’attributo facoltativo title, permette di associare un titolo al video.

Sitemap index

  • Nel caso in cui si disponga di moltissimi annunci o comunque per ragioni di comodità, è possibile utilizzare una sitemapindex che contenga i riferimenti a più sitemap. La struttura è la seguente:

<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex>
<sitemap>
<url>http://www.example.com/sitemap-lombardia1.xml</url>
<region>Lombardia</region>
</sitemap>
<sitemap>
<url>http://www.example.com/sitemap-lombardia2.xml</url>
<region>Lombardia</region>
</sitemap>
<sitemap>
<url>http://www.example.com/sitemap-sardegna.xml</url>
<region>Sardegna</region>
</sitemap>
</sitemapindex>
  • Il campo url è obbligatorio e deve contenere l’url (completo http://) di una sitemap.
  • Il campo region è facoltativo e contiene il riferimento ad una regione italiana. Tutti gli annunci presenti nella sitemap relativa, devono essere localizzati in tale regione.

Limiti e caveat

  • Non c’è un limite specifico alla dimensione dimensione di un singolo file (anche diversi GB sono gestiti senza particolari problemi), ma è consigliabile per praticità generare file di dimensione non superiore a 500 MB, eventualmente comprimendoli in formato zip o gz.
  • Generazione del feed. E’ sconsigliabile generare “al volo” (per ogni richiesta) il feed, salvo che non sia di dimensioni davvero molto contenute (<100 annunci), perché potrebbe portare facilmente a timeout in fase di scaricamento. Inoltre, poiché la generazione è comunque un processo potenzialmente lungo e gli orari di scaricamento da parte di Caasa sono variabili, è possibile che si verifichi un tentativo di scaricamento proprio durante la generazione del feed. Il modo migliore (e più semplice) di evitare problemi, consiste nel generare il feed con un nome diverso da quello utilizzato per scaricarlo e solo a generazione conclusa, rimuovere il file vecchio e rinominare quello nuovo (operazioni che si svolgono in pochi secondi o anche meno).
  • Indicare nella sitemap-index una regione per una determinata sitemap implica che CaasaBot utilizzi solo gli annunci effettivamente localizzati in città di quella regione. Eventuali altri annunci saranno scartati automaticamente.
  • Codifica dei caratteri. Nelle sitemap deve essere utilizzata la codifica UTF-8 e l’escape xml delle sole 5 entities predefinite per l’xml (&lt; == <, &gt; == >, &amp; == &, &apos; == , &quot; == : si veda il post su stackoverflow. Per evitare l’escape, è consigliabile utilizzare il tag <![CDATA[]]> per tutti i campi (come <title> e <description>) che potrebbero contenere facilmente qualcuno di questi 5 caratteri.
  • Nelle descrizioni, nel titolo e negli altri campi testuali, non è ammesso l’uso di html, che verrà rimosso in automatico. Anche le entities html (diverse dalle cinque xml) non dovrebbero essere presenti nel feed ma essere inserite come normali caratteri UTF-8. E’ possibile però (in alternativa) inserire dentro un blocco CDATA le entities html, sia in forma simbolica che numerica (es. è &egrave; o &#232;). N.B. Questa opzione non è disponibile fuori da un blocco CDATA dove la & iniziale delle entities devrebbe essere escapata.
  • Le url dei singoli annunci devono essere univoche (ovvero ad ogni annuncio deve corrispondere una diversa url). Le url devono inoltre essere formattate correttamente (compreso l’https:// iniziale, la corretta codifica degli eventuali caratteri speciali e l’escape xml della stringa risultante).
  • I singoli annunci devono essere accessibili: CaasaBot si riserva di scaricare comunque i singoli annunci per verificarne l’esistenza e la corrispondenza con le informazioni passate o per estrarre ulteriori informazioni.