Câmpurile unui anunț

Un anunț e un obiect JSON plat: fiecare informație e un câmp de prim nivel (price, rooms, floor), iar dotările sunt o listă de coduri (features). Aceleași câmpuri le trimiți la POST /listings/validate, POST /listings, PATCH /listings/{code} și PUT /listings/ref/{ref}. Pagina de față explică grupurile de câmpuri și dă câte un exemplu complet pe tipurile cele mai folosite. Lista completă, cu tipul și unitatea fiecărui câmp și cu tipurile de proprietate pentru care există, e în vocabular, la GET /schema.

Identitatea

string

obligatoriu

Tipul proprietății: apartment, house, room, complex, land, commercial, warehouse, garage, hospitality, special.

string

Subtipul, din vocabularul tipului (de exemplu studio, standard, penthouse la apartament; building, agricultural la teren). Obligatoriu pentru toate tipurile care au subtipuri, adică toate în afară de room și complex.

string

obligatoriu

sale (vânzare), rent (închiriere) sau short_stay (regim hotelier). Nu orice tip acceptă orice tranzacție: perechile valide sunt în types[].transactions din vocabular. Regimul hotelier se poate folosi doar când vocabularul îl marchează available: true.

Tipul și tranzacția nu se mai schimbă după creare.

Textul

string

obligatoriu

Titlul, între 10 și 90 de caractere, cu conținut real (nu „aaaaaaaaaa”).

string

obligatoriu

Descrierea, între 30 și 5.000 de caractere. Nu pune în text telefoane, emailuri sau adrese web: contactul trece prin pagina anunțului, iar moderarea respinge anunțurile cu date de contact în text.

string

Limba titlului și a descrierii, ca cod ISO 639-1 (ro, en). Dacă lipsește, Housera o deduce din text.

Locația

latitude, longitude, city și street sunt obligatorii pentru orice anunț. Opțional, trimiți county, area (cartierul), street_number și landmark (un reper apropiat). Detaliile sunt în ghidul de locație.

Prețul

integer

obligatoriu

Suma întreagă, în moneda din price_currency. Sensul urmează tranzacția: prețul total la vânzare, chiria pe lună la închiriere, prețul pe noapte în regim hotelier. E întotdeauna prețul întregii oferte, niciodată pe metru pătrat. Obligatoriu, cu excepția ansamblurilor (complex), unde prețul „de la” se calculează din tipurile de unități.

string

implicit:"EUR"

Codul ISO 4217 al monedei. Monedele acceptate sunt în currencies din vocabular (EUR, RON, USD și altele). Toate sumele anunțului (garanția, costurile suplimentare) sunt în aceeași monedă.

boolean

Prețul e negociabil.

În răspuns, price e valoarea în euro, pe care o compară căutarea, cu currency: "EUR". Suma și moneda în care ai trimis-o sunt în price_declared:

{ "price": 502, "currency": "EUR", "price_period": "month", "price_declared": { "amount": 2500, "currency": "RON" } }

Valoarea în euro urmează cursul de referință al zilei.

Suprafețele

Toate suprafețele sunt în m², cu cel mult două zecimale.

Câmp	Ce măsoară	Obligatoriu la
`usable_area_sqm`	Suprafața utilă.	toate tipurile, în afară de `land`, `house` și `complex`
`built_area_sqm`	Suprafața construită.	`house`
`land_area_sqm`	Suprafața terenului.	`land`, `house`

Vocabularul conține și suprafețele secundare (balcoane, terasă, curte, birouri, producție, depozitare), fiecare pe tipurile la care are sens.

Specificațiile

Câmpurile care descriu proprietatea: camere, etaj, an, stare, încălzire, certificat energetic și multe altele. Cele obligatorii depind de tip:

Câmp	Ce e	Obligatoriu la
`rooms`, `bedrooms`, `bathrooms`	Numărul de camere, dormitoare, băi. `bedrooms` și `bathrooms` pot fi `0`.	`apartment`, `house`
`floor`	Etajul, ca cod de nivel: `ground`, `floor_1` … `floor_99`, `semi_basement`, `basement`, `mezzanine`, `attic`, `roof_space`.	`apartment`, `room`
`total_floors`	Numărul de etaje ale clădirii (`0` = doar parter).	`apartment`, `house`
`partitioning`	Compartimentarea: `detached`, `semi_detached`, `undetached`, `circular`, `railroad`, `unknown`.	`apartment`, în afară de garsoniere și apartamentele cu o cameră
`attic`	Mansardă sau pod: `attic`, `roof_space`, `none`.	`house`
`flood_risk`	Declarația de risc de inundație, `true` sau `false`.	`land`, `house`

Câteva reguli utile:

Codurile, nu etichetele. Trimiți "condition": "renovated", nu "Renovat". Codurile și etichetele lor (în română și engleză) sunt în vocabular.
Etajul ca număr e acceptat: 3 e citit ca floor_3, 0 ca ground, -1 ca semi_basement. În răspunsuri primești mereu codul.
Booleenii sunt true sau false.
Listele (heating_types, orientations, materials) sunt liste de coduri, chiar și cu un singur element.
Codurile retrase rămân valabile: dacă trimiți un cod vechi, e citit ca succesorul lui (vezi retired în vocabular).

Dotările

features e o listă de coduri din catalogul de dotări, de exemplu ["ac", "elevator", "intercom"]. Catalogul are câteva sute de coduri, grupate (utilități, securitate, exterior, clădire…), fiecare cu tipurile de proprietate la care se aplică. Îl găsești în features din vocabular. O dotare care nu e în catalog sau nu se aplică tipului anunțului nu blochează scrierea: e ignorată și apare în warnings[].

Contactul

Numele și emailul de contact sunt cele ale contului care deține cheia. Telefonul e cel din cont, dacă nu trimiți altul:

string

Un număr de telefon valid. Se salvează în format internațional (E.164). Obligatoriu doar dacă în cont nu e niciun telefon.

Ce nu există pentru tip și tranzacție

Fiecare câmp există doar pentru anumite combinații de tip și tranzacție: garanția (deposit_months) doar la închiriere, numărul de porți de încărcare (dock_doors_count) doar la hale, compartimentarea doar la apartamente. Un câmp trimis acolo unde nu există nu e o eroare: e ignorat, iar răspunsul ți-l semnalează în warnings[]:

"warnings": [
  { "pointer": "/deposit_months", "code": "not_for_transaction" },
  { "pointer": "/partitioning", "code": "not_for_type" }
]

Așa poți trimite din CRM aceleași câmpuri pentru toate anunțurile, iar Housera păstrează doar ce are sens. Merită totuși să-ți curăți maparea până când warnings[] e gol.

Exemple complete

Toate exemplele de mai jos trec de validare așa cum sunt.

Apartament
Casă
Teren
Spațiu comercial

{
  "type": "apartment",
  "subtype": "standard",
  "transaction": "sale",
  "title": "Apartament 3 camere decomandat, Copou, Iași",
  "description": "Apartament luminos cu trei camere decomandate, renovat în 2022, la cinci minute de Parcul Copou. Bucătărie închisă, centrală proprie pe gaz, ferestre noi și boxă la subsol.",
  "city": "Iași",
  "county": "Iași",
  "area": "Copou",
  "street": "Strada Vasile Lupu",
  "street_number": "12",
  "latitude": 47.1752,
  "longitude": 27.5701,
  "price": 98000,
  "price_currency": "EUR",
  "negotiable": true,
  "rooms": 3,
  "bedrooms": 2,
  "bathrooms": 1,
  "floor": "floor_2",
  "total_floors": 4,
  "usable_area_sqm": 65.5,
  "built_area_sqm": 72,
  "partitioning": "detached",
  "year_built": 1985,
  "condition": "renovated",
  "heating_types": ["gas"],
  "energy_certificate": "b",
  "features": ["ac", "elevator", "intercom"]
}

{
  "type": "house",
  "subtype": "detached",
  "transaction": "sale",
  "title": "Casă individuală 4 camere cu curte, Bucium, Iași",
  "description": "Casă individuală pe parter și etaj, construită în 2018, cu patru camere, două băi și curte amenajată de 320 mp. Acces asfaltat, toate utilitățile, garaj și loc de parcare în curte.",
  "city": "Iași",
  "area": "Bucium",
  "street": "Strada Plopii fără Soț",
  "street_number": "7A",
  "latitude": 47.1238,
  "longitude": 27.6211,
  "price": 185000,
  "price_currency": "EUR",
  "rooms": 4,
  "bedrooms": 3,
  "bathrooms": 2,
  "total_floors": 1,
  "built_area_sqm": 140,
  "usable_area_sqm": 118,
  "land_area_sqm": 320,
  "attic": "none",
  "flood_risk": false,
  "year_built": 2018,
  "condition": "good",
  "heating_types": ["gas"],
  "features": ["garden", "fenced", "parking_open", "alarm"]
}

{
  "type": "land",
  "subtype": "building",
  "transaction": "sale",
  "title": "Teren intravilan 800 mp, deschidere 20 m, Miroslava",
  "description": "Teren intravilan plan, cu deschidere de 20 m la drum asfaltat, curent și apă la limita proprietății. PUZ aprobat pentru locuințe individuale, potrivit pentru o casă cu grădină.",
  "city": "Miroslava",
  "county": "Iași",
  "street": "Strada Principală",
  "latitude": 47.1486,
  "longitude": 27.5032,
  "price": 52000,
  "price_currency": "EUR",
  "land_area_sqm": 800,
  "flood_risk": false,
  "land_classification": "inside_built_up_area",
  "land_frontage": 20,
  "pot": 35,
  "cut": 0.9,
  "features": ["utility_electricity", "utility_water_mains", "utility_road", "zoning_plan_approved"]
}

{
  "type": "commercial",
  "subtype": "offices",
  "transaction": "rent",
  "title": "Spațiu de birouri 120 mp, open space, Piața Victoriei, București",
  "description": "Spațiu de birouri de 120 mp într-o clădire de clasă A, cu open space, două săli de ședințe și recepție. Acces 24/7, parcare subterană în clădire, la trei minute de metrou.",
  "city": "București",
  "county": "București",
  "area": "Piața Victoriei",
  "street": "Bulevardul Lascăr Catargiu",
  "street_number": "40",
  "latitude": 44.4517,
  "longitude": 26.0893,
  "price": 2400,
  "price_currency": "EUR",
  "deposit_months": 2,
  "usable_area_sqm": 120,
  "floor": "floor_3",
  "commercial_class": "a",
  "commercial_layout": "open_space",
  "features": ["ac", "access_24_7", "structured_cabling", "reception_area"]
}

Ansamblurile rezidențiale

Un ansamblu (complex) nu are un etaj, o suprafață sau un preț unic. În locul lor, trimiți lista tipurilor de unități în unit_types. Cel puțin un rând trebuie să fie complet: label, area_sqm, units_count și price_from.

"unit_types": [
  { "label": "2 camere", "rooms": 2, "area_sqm": 54, "area_sqm_to": 60, "units_count": 48, "price_from": 72000 },
  { "label": "3 camere", "rooms": 3, "area_sqm": 78, "units_count": 32, "price_from": 99000 }
]

Prețul afișat al ansamblului e cel mai mic price_from. Câmpurile de proiect (stadiul, termenul de livrare, regimul de înălțime) sunt în vocabular, la câmpurile care au complex între tipuri.

Linkuri media

object

Linkuri externe, http sau https, de cel mult 500 de caractere: video (un film de prezentare), tour (un tur virtual), plan (un plan).

Început

Concepte

Ghiduri

Referință

Mai departe

Câmpurile unui anunț

Identitatea

Textul

Locația

Prețul

Suprafețele

Specificațiile

Dotările

Contactul

Ce nu există pentru tip și tranzacție

Exemple complete

Ansamblurile rezidențiale

Linkuri media

​Identitatea

​Textul

​Locația

​Prețul

​Suprafețele

​Specificațiile

​Dotările

​Contactul

​Ce nu există pentru tip și tranzacție

​Exemple complete

​Ansamblurile rezidențiale

​Linkuri media

Identitatea

Textul

Locația

Prețul

Suprafețele

Specificațiile

Dotările

Contactul

Ce nu există pentru tip și tranzacție

Exemple complete

Ansamblurile rezidențiale

Linkuri media