Vocabularul

GET /schema e lista completă și mereu actuală a codurilor pe care le folosește API-ul: tipuri și subtipuri de proprietate, tranzacții, monede, câmpuri, niveluri, dotări. E construit din aceleași reguli pe care le aplică formularul Housera, deci ce acceptă formularul e exact ce publică vocabularul. E public: nu cere cheie, ca să-l poți citi înainte să-ți faci cont.

curl "https://housera.ro/api/v1/schema?locale=ro"

Nu copia listele din vocabular în codul tău. Citește-le din GET /schema (de exemplu la pornirea aplicației sau o dată pe zi) și construiește-ți maparea pe ele. Așa, un subtip sau o dotare nouă apare la tine fără modificări de cod.

Ce conține

{
  "locale": "ro",
  "version": "v1",
  "types": [
    {
      "code": "apartment",
      "label": "Apartament",
      "transactions": ["sale", "rent", "short_stay"],
      "subtypes": [{ "code": "studio", "label": "Garsonieră" }, { "code": "standard", "label": "Apartament standard" }]
    }
  ],
  "transactions": [
    { "code": "sale", "label": "De vânzare", "available": true, "price_period": "total" },
    { "code": "rent", "label": "De închiriat", "available": true, "price_period": "month" }
  ],
  "currencies": ["EUR", "RON", "USD"],
  "fields": {
    "usable_area_sqm": {
      "type": "decimal",
      "unit": "m2",
      "types": ["apartment", "house", "room", "commercial", "warehouse", "garage", "hospitality", "special"],
      "transactions": ["sale", "rent", "short_stay"],
      "values": null
    },
    "condition": {
      "type": "code",
      "unit": null,
      "types": ["apartment", "house", "room"],
      "transactions": ["sale", "rent", "short_stay"],
      "values": [{ "code": "new", "label": "Nou" }, { "code": "renovated", "label": "Renovat" }]
    },
    "floor": { "type": "level", "unit": null, "values": null, "values_from": "levels" }
  },
  "levels": {
    "values": [{ "code": "ground", "label": "Parter" }, { "code": "basement", "label": "Subsol" }],
    "numbered": { "pattern": "floor_{n}", "min": 1, "max": 99, "label": "Etaj {n}" }
  },
  "field_types": [{ "code": "integer", "label": "Număr întreg" }],
  "units": [{ "code": "m2", "label": "m²" }],
  "features": [
    { "code": "ac", "label": "Aer condiționat", "group": "indoor_comfort", "types": ["apartment", "house"], "transactions": null }
  ],
  "photo_rooms": [{ "code": "living", "label": "Living" }],
  "street_types": [{ "code": "street", "label": "Strada" }],
  "retired": [
    { "kind": "feature", "code": "parking", "replaced_by": "parking_open", "retired_on": "2026-09-16" }
  ]
}

Exemplul e scurtat: fiecare listă are în realitate toate elementele.

Cheie	Ce găsești
`types`	Tipurile de proprietate, cu tranzacțiile permise și subtipurile fiecăruia.
`transactions`	Tranzacțiile, cu `price_period` (ce cumpără prețul: `total`, `month`, `night`) și `available` (dacă tranzacția e deschisă acum pe platformă).
`currencies`	Monedele acceptate în `price_currency`.
`fields`	Fiecare câmp al anunțului: tipul valorii, unitatea, tipurile de proprietate și tranzacțiile la care există, valorile permise.
`levels`	Codurile de nivel, pentru `floor` și pentru eticheta `floor` a pozelor.
`field_types`	Tipurile de valori folosite în `fields`.
`units`	Unitățile folosite în `fields`.
`features`	Catalogul de dotări, cu grupul și tipurile de proprietate la care se aplică fiecare.
`street_types`	Tipurile de stradă (stradă, bulevard, șosea…), cu codul și eticheta.
`photo_rooms`	Codurile de încăperi pentru etichetele pozelor.
`retired`	Codurile retrase și succesorii lor.

Câmpurile

Fiecare intrare din fields îți spune:

type, felul valorii: integer, decimal, boolean, text, code (o valoare din values), codes (o listă de valori din values), level (un cod de nivel), time (HH:MM), date (AAAA-LL-ZZ), country (ISO 3166-1 alpha-2), currency (ISO 4217), coordinates, object, objects;
unit, pentru numere: m2, m, year, month, night, percent, kw, count și altele, plus currency, adică moneda anunțului (price_currency);
types și transactions, combinațiile la care câmpul există. În afara lor, câmpul e ignorat și semnalat în warnings[];
values, codurile permise, cu etichete. Când lipsesc, values_from arată unde sunt (de exemplu levels sau currencies);
values_by_type, când valorile permise diferă de la un tip de proprietate la altul (de exemplu materialele de construcție ale unei hale față de ale unei case).

Vocabularul nu spune ce câmpuri sunt obligatorii; regulile acestea sunt în Câmpurile unui anunț. Cel mai sigur test rămâne POST /listings/validate.

Codurile retrase

Un cod nu dispare niciodată. Când un cod se schimbă, cel vechi trece în retired, cu succesorul lui:

{ "kind": "value:partitioning", "code": "decomandat", "replaced_by": "detached", "retired_on": "2026-10-17" }

kind spune ce fel de cod e: feature, subtype, field (un câmp redenumit) sau value:<câmp> (o valoare a unui câmp).
Dacă trimiți codul vechi, Housera îl citește ca pe succesor. Nu pierzi nimic și nu primești eroare.
În răspunsuri primești mereu codul nou. Actualizează-ți maparea când vezi un cod al tău în retired.

Limba etichetelor

locale=ro (implicit) sau locale=en schimbă doar etichetele (label). Codurile nu se traduc niciodată: apartment rămâne apartment în orice limbă.

curl "https://housera.ro/api/v1/schema?locale=en"

Cache

Vocabularul se schimbă rar. Răspunsul are antetul ETag și poate fi păstrat în cache o oră. Ca să verifici ieftin dacă s-a schimbat, trimite ETag-ul primit în If-None-Match:

curl -i "https://housera.ro/api/v1/schema" \
  -H 'If-None-Match: "919efa73ab07e521d4f92bbc2e5b65f0"'

Dacă nu s-a schimbat nimic, primești 304 Not Modified, fără corp. Limita pentru GET /schema e de 60 de cereri pe minut per adresă IP, separată de limita cheilor tale.

Început

Concepte

Ghiduri

Referință

Mai departe

Ce conține

Câmpurile

Codurile retrase

Limba etichetelor

Cache

​Ce conține

​Câmpurile

​Codurile retrase

​Limba etichetelor

​Cache

Ce conține

Câmpurile

Codurile retrase

Limba etichetelor

Cache