Immobili
Il catalogo, e il tuo patrimonio al suo interno. Gli endpoint di lettura coprono tutto ciò che deteniamo; quelli di scrittura toccano soltanto le schede pubblicate dalla tua organizzazione.
/v1/api/propertiesproperties:readElencare gli immobili
Scorri il catalogo per pagine, con i filtri.
L'endpoint di lettura di tutti i giorni. I filtri si combinano con un AND. Ciò che ometti resta senza vincoli, quindi una chiamata senza filtri restituisce l'intero catalogo nell'ordine del cursore.
Parametri di query
| Nome | Tipo | Descrizione |
|---|---|---|
city | string | Città a cui restringere, così come compare nell'indirizzo di un immobile. esempio: Berlin |
district | string | Quartiere all'interno della città. esempio: Kreuzberg |
postal_code | string | CAP a cui restringere. esempio: 10999 |
type | enum | Genere di immobile. apartment | house | studio | villa | penthouse | loft | townhouse | other esempio: apartment |
transaction_type | enum | Restringere alle vendite o agli affitti. sale | rent esempio: sale |
status | enum | Stato dell'annuncio. Omettilo per ottenere tutti gli stati e non solo quelli attivi. active | archived | sold | flagged esempio: active |
external_id | string | Il tuo identificatore di una scheda, per ritrovare ciò che ha creato un'importazione. esempio: OBJ-10041 |
min_price | number | Limite inferiore incluso del prezzo richiesto. esempio: 250000 |
max_price | number | Limite superiore incluso del prezzo richiesto. esempio: 750000 |
min_living_area | number | Limite inferiore incluso della superficie abitabile, in metri quadri. esempio: 60 |
min_bedrooms | integer | Limite inferiore incluso del numero di camere. esempio: 2 |
limit | integer | Schede per pagina. predefinito: 50esempio: 50 |
cursor | string | Puntatore opaco ricevuto nella risposta precedente. Omettilo per la prima pagina. I cursori sono stabili rispetto agli inserimenti, quindi la paginazione non salta né ripete mai una scheda, come invece fa uno scostamento. esempio: eyJpZCI6InByb3BfMWI3N2UwYTRmMiJ9 |
sort | string | Campo su cui ordinare. Anteponi un meno per l'ordine decrescente. esempio: -created_at |
expand | enum | Schede collegate da includere direttamente invece di richiederle a parte. images | price_history | market | translations esempio: images |
language | string | Rispondere in questa lingua quando l'immobile la possiede, come codice ISO 639-1. Un immobile che non possiede la lingua mantiene il proprio testo anziché ricevere risposta in un'altra, e la risposta indica in quale lingua è tornata. A riempirlo sono i feed che portano più lingue. esempio: es |
Risposta
{
"data": [
{ "id": "prop_8f2a41c9d0", "title": "Top-floor apartment…", "price": 42900000 },
{ "id": "prop_1b77e0a4f2", "title": "Garden flat…", "price": 38500000 }
],
"meta": {
"has_more": true,
"next_cursor": "eyJpZCI6InByb3BfMWI3N2UwYTRmMiJ9",
"limit": 50
}
}https://api.skautik.com/v1/api/properties
GET /v1/api/properties?city=Berlin&district=Kreuzberg&postal_code=10999 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/searchproperties:readCercare immobili
Ricerca semantica e geografica troppo complessa per una stringa di query.
Accetta un'interrogazione in linguaggio naturale, un poligono disegnato, o entrambi. I risultati tornano ordinati per pertinenza e non per una colonna ordinabile, quindi questo endpoint ignora il parametro sort. È un POST perché un poligono non sta in un URL, non perché modifichi qualcosa.
Campi del corpo
| Nome | Tipo | Descrizione |
|---|---|---|
query | string | Descrizione in linguaggio comune di ciò che si cerca. esempio: "quiet two bedroom near a park, needs a home office" |
polygon | array | Anello chiuso di coppie [longitudine, latitudine], nell'ordine GeoJSON. esempio: [[13.3702, 52.4812], [13.4791, 52.4812], [13.4791, 52.5401], [13.3702, 52.5401], [13.3702, 52.4812]] |
bounds | object | Rettangolo con sw_lat, sw_lng, ne_lat, ne_lng. Mutuamente esclusivo con polygon. esempio: {"north": 52.5401, "south": 52.4812, "east": 13.4791, "west": 13.3702} |
filters | object | Le stesse chiavi che l'endpoint di elenco accetta come parametri di query. esempio: {"property_type": "apartment", "price_max": 60000000} |
limit | integer | Risultati da restituire, da 1 a 200. predefinito: 50esempio: 50 |
Corpo della richiesta
{
"query": "quiet two bedroom near a park, needs a home office",
"filters": {
"market": "berlin-de",
"transaction_type": "sale",
"price_max": 50000000
},
"limit": 20
}Risposta
{
"data": [
{
"id": "prop_8f2a41c9d0",
"title": "Top-floor apartment…",
"relevance": 0.87,
"matched_on": ["quiet street", "park within 300m", "study alcove"]
}
],
"meta": { "has_more": false, "limit": 20 }
}https://api.skautik.com/v1/api/properties/search
POST /v1/api/properties/search HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"query": "quiet two bedroom near a park, needs a home office",
"filters": {
"market": "berlin-de",
"transaction_type": "sale",
"price_max": 50000000
},
"limit": 20
}/v1/api/properties/{property_id}properties:readRecuperare un immobile
Un immobile con l'insieme completo dei suoi attributi.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
property_idobbligatorio | string | Identificatore restituito da qualsiasi endpoint di raccolta. esempio: prop_8f2a41c9d0 |
Parametri di query
| Nome | Tipo | Descrizione |
|---|---|---|
expand | enum | Schede collegate da includere direttamente invece di richiederle a parte. images | price_history | market | translations esempio: images |
language | string | Rispondere in questa lingua quando l'immobile la possiede, come codice ISO 639-1. Un immobile che non possiede la lingua mantiene il proprio testo anziché ricevere risposta in un'altra, e la risposta indica in quale lingua è tornata. A riempirlo sono i feed che portano più lingue. esempio: es |
Risposta
{
"data": {
"id": "prop_8f2a41c9d0",
"title": "Top-floor apartment with a south-facing balcony",
"property_type": "apartment",
"transaction_type": "sale",
"price": 42900000,
"currency": "EUR",
"price_period": null,
"price_per_area": 579700,
"bedrooms": 2,
"bathrooms": 1,
"rooms": 3,
"living_area": 74,
"floor": 4,
"total_floors": 4,
"year_built": 1908,
"energy_label": "C",
"address": {
"street": "Oranienstrasse",
"postal_code": "10999",
"district": "Kreuzberg",
"city": "Berlin",
"country": "DE"
},
"location": {
"latitude": 52.4993,
"longitude": 13.4184,
"precision": "street"
},
"status": "active",
"listed_at": "2026-07-28T09:12:04Z",
"last_verified_at": "2026-08-11T04:00:00Z",
"updated_at": "2026-08-11T04:00:00Z"
}
}Risposte degne di nota
- 404
- Identificatore sconosciuto, oppure una scheda che la tua chiave non può vedere. Trattalo come un'assenza.
https://api.skautik.com/v1/api/properties/{property_id}
GET /v1/api/properties/prop_8f2a41c9d0?expand=images&language=es HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/{property_id}/price-historyproperties:readStorico dei prezzi
Tutti i prezzi richiesti osservati mentre seguivamo l'annuncio.
Sono prezzi pubblicizzati, non di compravendita. Un immobile può benissimo essere stato venduto a una cifra piuttosto diversa dal suo ultimo prezzo richiesto.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
property_idobbligatorio | string | Identificatore dell'immobile. esempio: prop_8f2a41c9d0 |
Risposta
{
"data": [
{ "price": 44900000, "currency": "EUR", "observed_at": "2026-07-28T09:12:04Z" },
{ "price": 42900000, "currency": "EUR", "observed_at": "2026-08-09T06:31:11Z" }
]
}https://api.skautik.com/v1/api/properties/{property_id}/price-history
GET /v1/api/properties/prop_8f2a41c9d0/price-history HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/{property_id}/similarGrowth and aboveproperties:readImmobili simili
Schede comparabili, per dare contesto o supportare una valutazione.
La somiglianza combina posizione, dimensione, tipo e stato. È una comodità, non una perizia, e i comparabili si diradano in fretta nelle zone con poca offerta.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
property_idobbligatorio | string | Immobile con cui confrontare. esempio: prop_8f2a41c9d0 |
Parametri di query
| Nome | Tipo | Descrizione |
|---|---|---|
limit | integer | Comparabili da restituire, da 1 a 50. esempio: 10 |
https://api.skautik.com/v1/api/properties/{property_id}/similar
GET /v1/api/properties/prop_8f2a41c9d0/similar?limit=10 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/propertiesproperties:writeCreare un immobile
Pubblica una scheda del tuo patrimonio.
Invia una Idempotency-Key perché una richiesta ripetuta non possa creare un annuncio duplicato. Le schede create in questo modo appartengono alla tua organizzazione e sono le uniche che la tua chiave può modificare.
Campi del corpo
| Nome | Tipo | Descrizione |
|---|---|---|
external_id | string | Il tuo identificatore per questo immobile. È facoltativo, ma conviene impostarlo se la scheda potrebbe arrivare più avanti tramite un'importazione: senza di esso l'importazione non ha nulla su cui fare corrispondenza e crea un duplicato. esempio: AG-4471-0812 |
titleobbligatorio | string | Titolo dell'annuncio. esempio: Top-floor apartment with a south-facing balcony |
property_typeobbligatorio | enum | Uno dei tipi di immobile supportati. esempio: apartment |
transaction_typeobbligatorio | enum | sale oppure rent. esempio: sale |
priceobbligatorio | integer | Importo in unità minori. esempio: 48900000 |
currencyobbligatorio | string | Codice ISO 4217. esempio: EUR |
addressobbligatorio | object | Come minimo una città e un paese; più informazioni ci sono, migliore è la precisione della geocodifica. esempio: {"street": "Oranienstrasse 12", "postal_code": "10999", "city": "Berlin", "country": "DE"} |
Intestazioni
| Nome | Tipo | Descrizione |
|---|---|---|
Idempotency-Key | string | Unica per ogni creazione logica. Ripetere la stessa chiave restituisce il risultato originale invece di creare una seconda scheda. esempio: a2f1c7e4-… |
Corpo della richiesta
{
"title": "Top-floor apartment with a south-facing balcony",
"property_type": "apartment",
"transaction_type": "sale",
"price": 42900000,
"currency": "EUR",
"living_area": 74,
"bedrooms": 2,
"address": {
"street": "Oranienstrasse",
"postal_code": "10999",
"city": "Berlin",
"country": "DE"
}
}Risposte degne di nota
- 201
- Creato. L'intestazione Location riporta l'URL della nuova risorsa.
- 409
- Una Idempotency-Key è stata riutilizzata con un corpo diverso.
- 422
- Il corpo è stato analizzato ma non ha superato la validazione. Vedi l'array errors.
https://api.skautik.com/v1/api/properties
POST /v1/api/properties HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"title": "Top-floor apartment with a south-facing balcony",
"property_type": "apartment",
"transaction_type": "sale",
"price": 42900000,
"currency": "EUR",
"living_area": 74,
"bedrooms": 2,
"address": {
"street": "Oranienstrasse",
"postal_code": "10999",
"city": "Berlin",
"country": "DE"
}
}/v1/api/properties/{property_id}properties:writeAggiornare un immobile
Modifica i campi di una scheda che hai pubblicato.
È un aggiornamento parziale: invia solo ciò che cambia. Invia If-Match con l'ETag della tua ultima lettura per non sovrascrivere una modifica concorrente. Una scheda che appartiene a una fonte di importazione viene rifiutata qui, perché la passata successiva annullerebbe quanto hai scritto: modificala nel sistema che alimenta l'importazione.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
property_idobbligatorio | string | Immobile da aggiornare. esempio: prop_8f2a41c9d0 |
Intestazioni
| Nome | Tipo | Descrizione |
|---|---|---|
If-Match | string | ETag della tua ultima lettura. Rifiutato con 412 se la scheda è cambiata nel frattempo. esempio: "3f8a2c1d9b" |
Corpo della richiesta
{
"title": "Top-floor apartment with a south-facing balcony and new windows",
"listing": {
"price": 419000,
"status": "active"
}
}Risposte degne di nota
- 403
- La scheda esiste ma non è stata pubblicata dalla tua organizzazione.
- 409
- managed_by_import. La scheda appartiene a una fonte di importazione, che fa fede su di essa. Il corpo indica quale sia la fonte.
- 412
- L'If-Match non ha corrisposto. Rileggi e riapplica la tua modifica.
https://api.skautik.com/v1/api/properties/{property_id}
PATCH /v1/api/properties/prop_8f2a41c9d0 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"title": "Top-floor apartment with a south-facing balcony and new windows",
"listing": {
"price": 419000,
"status": "active"
}
}/v1/api/properties/{property_id}properties:writeRitirare un immobile
Togli dal mercato una delle tue schede.
Ritirare non è cancellare. La scheda passa allo stato ritirato, sparisce dalla ricerca e mantiene il suo storico dei prezzi perché le analisi passate restino comprensibili. Una scheda che appartiene a una fonte di importazione viene rifiutata, perché la passata successiva la riporterebbe subito indietro: ritirala alla fonte.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
property_idobbligatorio | string | Immobile da ritirare. esempio: prop_8f2a41c9d0 |
Risposte degne di nota
- 204
- Ritirato. Nessun corpo.
- 409
- managed_by_import. Ritiralo alla fonte, oppure elimina prima la fonte.
https://api.skautik.com/v1/api/properties/{property_id}
DELETE /v1/api/properties/prop_8f2a41c9d0 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/{property_id}/imagesproperties:readElencare le immagini
Le schede immagine di un immobile, nell'ordine di visualizzazione.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
property_idobbligatorio | string | Identificatore dell'immobile. esempio: prop_8f2a41c9d0 |
https://api.skautik.com/v1/api/properties/{property_id}/images
GET /v1/api/properties/prop_8f2a41c9d0/images HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/{property_id}/imagesimages:writeCaricare un'immagine
Allega un'immagine a una scheda che hai pubblicato.
Caricamento multipart. JPEG, PNG o WebP fino a 12 MB. Carica solo immagini di cui detieni i diritti: la fotografia immobiliare di solito è concessa in licenza a un'agenzia più che posseduta.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
property_idobbligatorio | string | Immobile a cui allegarla. esempio: prop_8f2a41c9d0 |
Parametri di query
| Nome | Tipo | Descrizione |
|---|---|---|
room_type | string | Cosa mostra la fotografia; serve a raggruppare le immagini e a scegliere una fonte per l'allestimento. esempio: living_room |
primary | boolean | Passa true per renderla l'immagine principale, retrocedendo quella attuale. esempio: true |
Campi del corpo
| Nome | Tipo | Descrizione |
|---|---|---|
fileobbligatorio | binary | Contenuto dell'immagine. esempio: listings.csv |
position | integer | Ordine di visualizzazione. L'immagine in posizione 0 è quella principale. esempio: 1 |
Risposte degne di nota
- 413
- Il file supera il limite di dimensione.
- 415
- Formato immagine non supportato.
https://api.skautik.com/v1/api/properties/{property_id}/images
POST /v1/api/properties/prop_8f2a41c9d0/images?room_type=living_room&primary=true HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"file": "listings.csv",
"position": 1
}/v1/api/properties/{property_id}/images/{image_id}images:writeEliminare un'immagine
Rimuovi un'immagine da una scheda che hai pubblicato.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
property_idobbligatorio | string | Identificatore dell'immobile. esempio: prop_8f2a41c9d0 |
image_idobbligatorio | string | Identificatore dell'immagine. esempio: img_2b7d4f1908 |
https://api.skautik.com/v1/api/properties/{property_id}/images/{image_id}
DELETE /v1/api/properties/prop_8f2a41c9d0/images/img_2b7d4f1908 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…