Seleziona una pagina

Formato xml per la sottomissione degli annunci

versione 1.05 – marzo 2017

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>Quadrivano luminoso pressi via Vesalio</title>
             <description>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>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>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 http://) 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 http://) 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

  • Un singolo file non può avere una dimensione superiore a 50 MB. Può essere però compresso in formato gz.
  • 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.
  • Nelle sitemap deve essere utilizzata la codifca UTF-8.
  • Nelle descrizioni, nel titolo e negli altri campi testuali, non è ammesso l’uso di html.  Devono essere escapati esclusivamente le 5 entities predefinite per l’xml (&lt; == <, &gt; == >, &amp; == &, &apos; == , &quot; == ).
  • 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’http:// 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.
Share This