Tutto quello che serve per integrare i tuoi annunci. Specifiche del feed JSON, campi, esempi e validazione. Versione schema: 1.0
Il feed UniRoom è un file JSON che pubblichi su un URL pubblico del tuo sito. Il nostro sistema lo scarica automaticamente più volte al giorno e mostra i tuoi annunci agli studenti con criteri compatibili.
Non devi occuparti di inviare dati, aggiornare endpoint o gestire autenticazioni: esponi il file, noi lo leggiamo. Se modifichi un annuncio, aggiorni il file. Se lo rimuovi, lo togli dal file. Il resto è automatico.
Il feed segue il principio del full replacement: il file contiene sempre tutti i tuoi annunci attivi in un dato momento. Un annuncio che non è presente nel feed viene considerato rimosso.
Il feed è un singolo oggetto JSON con metadati a livello root e un array di annunci.
{
"feed_version": "1.0",
"partner_id": "il-tuo-partner-id",
"generated_at": "2026-04-24T10:30:00Z",
"listings": [
{ ...annuncio 1... },
{ ...annuncio 2... },
...
]
}Metadati del feed, tutti obbligatori.
feed_version
string
obbligatorio
Versione dello schema. Valore attuale: "1.0".
Ci permette di evolvere lo schema senza rompere i feed dei partner esistenti.
partner_id
string
obbligatorio
Identificativo del partner assegnato da UniRoom al momento dell'attivazione. Te lo comunichiamo via email quando approviamo la tua candidatura.
generated_at
string (ISO 8601)
obbligatorio
Timestamp di generazione del feed. Usato da noi per monitorare la freschezza e diagnosticare problemi.
Esempio: "2026-04-24T10:30:00Z"
listings
array
obbligatorio
Array degli annunci. Può essere vuoto se non hai annunci attivi al momento, ma deve essere presente come array ([]).
Limite massimo: 10.000 annunci per singolo feed.
Campi che devono sempre essere presenti in ogni annuncio.
id
string, max 100
ID univoco nel sistema del partner. Deve rimanere stabile nel tempo: stesso annuncio = stesso id nei feed successivi. UniRoom usa questo campo per capire se un annuncio è nuovo, aggiornato o da rimuovere.
title
string, 5-200 caratteri
Titolo breve dell'annuncio. Esempio: "Stanza singola luminosa zona Porta Romana".
url
string (URL), max 500
Link diretto all'annuncio sul tuo sito. Deve essere pubblicamente accessibile: quando uno studente clicca, arriva qui senza intermediazioni.
price
number, 50-5000
Prezzo mensile in euro, solo il numero (es. 450 o 450.00).
Sempre mensile, mai settimanale o per notte.
city
string, max 100
Il comune amministrativo dell'immobile (es. "Milano", "Padova").
Scrivi sempre il nome reale del comune, anche per immobili in comuni limitrofi alle città universitarie
(es. "Sesto San Giovanni", "Cinisello Balsamo"):
li mostriamo agli studenti che cercano nelle aree metropolitane vicine.
address
string, max 250
Indirizzo dell'immobile (es. "Via Venezia 15", "Viale Bligny 35") oppure zona descrittiva in mancanza di indirizzo esatto (es. "Zona Navigli").
Più preciso è, meglio funziona il matching. Se fornisci anche coordinate (latitude/longitude), useremo direttamente quelle.
room_type
enum
Tipo di stanza. Valori ammessi:
"single"
singola
·
"double"
doppia
·
"bed"
posto letto
updated_at
string (ISO 8601)
Data di ultimo aggiornamento dell'annuncio. Esempio: "2026-04-23T15:22:00Z".
Campi non obbligatori ma fortemente consigliati: migliorano la qualità del match.
latitude
number | null, -90 / 90
Latitudine dell'immobile in formato decimale WGS84 (es. 45.4587 per Milano).
Se fornita, saltiamo il geocoding automatico — più preciso e più veloce.
Va sempre insieme a longitude: o entrambe valorizzate, o entrambe null.
longitude
number | null, -180 / 180
Longitudine dell'immobile in formato decimale WGS84 (es. 9.2089 per Milano).
Va sempre insieme a latitude: o entrambe valorizzate, o entrambe null.
description
string | null, max 2000
Descrizione testuale dell'annuncio. Solo plain text, no HTML.
available_from
string (ISO date) | null
Data di disponibilità (es. "2026-09-01"). Se null, assumiamo disponibilità immediata.
images
array | null, max 10 URL
Array di URL immagini pubblicamente accessibili via HTTPS. Puoi inviarne fino a 10 — attualmente UniRoom utilizza solo la prima come immagine di anteprima, ma è meglio inviare quelle disponibili per futuri sviluppi.
Campi opzionali che arricchiscono il matching con le preferenze degli studenti.
bills_included
boolean | null
Se true, il prezzo mensile include le utenze (luce, gas, acqua, internet).
Se false, le bollette sono a parte. Se null,
il dato non è noto e per default assumiamo che le bollette siano a parte.
Un feed valido con tre annunci: il primo completo, il secondo parzialmente valorizzato, il terzo minimale.
Il file completo è disponibile per il download. Puoi usarlo come template: sostituisci i dati di esempio con i tuoi annunci reali, mantenendo la struttura.
Sempre UTF-8. Caratteri speciali italiani (à, è, ò, ù) devono essere scritti come caratteri reali, non come entità HTML.
Prezzi come number JSON standard con punto come separatore decimale:
450 o 450.00. Mai stringhe come "450,00".
Sempre ISO 8601, UTC quando possibile:
timestamp completo "2026-04-24T10:30:00Z",
solo data "2026-09-01".
Se fornisci latitude e longitude, devono essere in formato decimale WGS84 (es. 45.4642, 9.1900).
Non accettiamo formati gradi-minuti-secondi. Le due coordinate vanno sempre insieme: o entrambe valorizzate, o entrambe null.
Devono essere accessibili pubblicamente via HTTPS, senza autenticazione. UniRoom referenzia gli URL ma non scarica le immagini.
Fondamentale: lo stesso annuncio deve avere sempre lo stesso id.
Se cambi l'id tra un feed e l'altro, noi lo trattiamo come un nuovo annuncio.
Full replacement: ometti l'annuncio dal feed e UniRoom lo rimuove automaticamente. Non servono flag né endpoint separati.
Soft limit: 10.000 annunci per feed. Oltre, contattaci per gestione paginata.
Puoi validare il tuo feed prima di pubblicarlo usando il nostro JSON Schema standard. Funziona con qualsiasi libreria JSON Schema (Ajv per Node.js, jsonschema per Python, .NET, etc).
Best practice: integra la validazione nella tua pipeline di deploy. Se il feed non passa la validazione, blocca la pubblicazione. Previeni errori prima che arrivino a UniRoom.
| Errore | Gravità | Comportamento |
|---|---|---|
| JSON malformato | Fatale | Rifiuta tutto il feed |
| Campo root obbligatorio mancante | Fatale | Rifiuta tutto il feed |
partner_id non riconosciuto |
Fatale | Rifiuta tutto il feed |
| Annuncio non conforme allo schema | Soft | Salta quell'annuncio, gli altri vengono processati |
| Città non supportata | Soft | Salta quell'annuncio, le città disponibili sono nella FAQ |
Le domande tecniche più comuni dei partner.
Di default una volta all'ora. Per partner con alta rotazione di annunci possiamo aumentare la frequenza, parlane con noi.
Supportiamo anche il header If-Modified-Since per ridurre il carico quando non ci sono cambiamenti.
Manteniamo l'ultima versione valida. Dopo 10 fetch consecutivi falliti, il partner passa in stato "degraded" e riceviamo una notifica per verificare. Gli annunci già indicizzati restano visibili.
No, il feed deve essere pubblicamente accessibile via HTTPS GET. Se vuoi limitare l'accesso solo a UniRoom, puoi configurare una whitelist di IP sul tuo server: contattaci e ti forniremo i nostri.
Attualmente supportiamo Milano, Roma, Torino, Bologna, Padova, Firenze e i rispettivi comuni limitrofi. Annunci per altre città vengono al momento esclusi dalla pubblicazione, ma teniamo traccia delle richieste per pianificare nuove aperture. Se operi in città non ancora supportate, scrivici: valutiamo l'espansione in base alla domanda.
Al momento supportiamo un feed per partner. Se gestisci molte città con strutture dati separate, contattaci: valuteremo caso per caso se aggiungere multi-feed.
Il tracciato è rigoroso: accettiamo esclusivamente i campi documentati in questa pagina. Campi aggiuntivi non previsti faranno fallire la validazione dell'annuncio. Se hai un dato specifico che pensi possa essere utile al matching, scrivici: valutiamo di aggiungerlo al tracciato ufficiale per una futura versione dello schema.
Il campo feed_version indica la versione dello schema che il tuo feed rispetta. Quando pubblicheremo una nuova versione, manterremo comunque il supporto alla 1.0 per un periodo di transizione di almeno 6 mesi, con preavviso scritto via email.
Quando rileviamo errori nel feed (annunci scartati, città non supportate, problemi di formato), inviamo automaticamente un report via email al referente tecnico indicato in fase di integrazione. Riceverai al massimo una notifica al giorno con il riepilogo degli errori. Ti scriviamo solo quando rileviamo problemi: l'assenza di email significa che tutto procede normalmente.
Il team UniRoom ti supporta in ogni fase. Scrivici e ti risponderemo entro 48 ore.
Contattaci