> ## Documentation Index
> Fetch the complete documentation index at: https://api.housera.ro/llms.txt
> Use this file to discover all available pages before exploring further.

# Vocabularul

> GET /schema: tipurile, câmpurile, unitățile, dotările și codurile retrase, mereu la zi.

`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.

```bash theme={null}
curl "https://housera.ro/api/v1/schema?locale=ro"
```

<Tip>
  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.
</Tip>

## Ce conține

```json theme={null}
{
  "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ț](/ro/guides/listing-payload). 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:

```json theme={null}
{ "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ă.

```bash theme={null}
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`:

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.