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

# The Vocabulary

> GET /schema: the types, fields, units, amenities, and retired codes, always up to date.

`GET /schema` is the complete and always current list of codes used by the API: types and subtypes of property, transactions, currencies, fields, levels, amenities. It is built from the same rules that the Housera form applies, so what the form accepts is exactly what the vocabulary publishes.

It is **public**: it doesn't require a key, so you can read it before you create your account.

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

<Tip>
  Do not copy the lists from the vocabulary into your code. Read them from `GET /schema` (for example, when launching the application or once a day) and build your mapping on them. This way, a new subtype or amenity appears on your end without code modifications.
</Tip>

## What it contains

```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" }
  ]
}
```

The example is shortened: each list actually contains all elements.

| Key | What you find |
| - | - |
| `types` | Property types, with the allowed transactions and subtypes of each. |
| `transactions` | Transactions, with `price_period` (what the price buys: `total`, `month`, `night`) and `available` (if the transaction is currently open on the platform). |
| `currencies` | Accepted currencies in `price_currency`. |
| `fields` | Each field of the listing: the type of value, the unit, the property types and transactions it exists for, the allowed values. |
| `levels` | Level codes, for `floor` and for the label `floor` of the photos. |
| `field_types` | Types of values used in `fields`. |
| `units` | Units used in `fields`. |
| `features` | The catalog of amenities, with the group and types of property to which each applies. |
| `street_types` | Types of street (street, boulevard, road…), with the code and label. |
| `photo_rooms` | Room codes for photo labels. |
| `retired` | Retired codes and their successors. |

## Fields

Each entry in `fields` tells you:

* **`type`**, the type of value: `integer`, `decimal`, `boolean`, `text`, `code` (a value from `values`), `codes` (a list of values from `values`), `level` (a level code), `time` (`HH:MM`), `date` (`AAAA-LL-ZZ`), `country` (ISO 3166-1 alpha-2), `currency` (ISO 4217), `coordinates`, `object`, `objects`;
* **`unit`**, for numbers: `m2`, `m`, `year`, `month`, `night`, `percent`, `kw`, `count` and others, plus `currency`, that is, the currency of the listing (`price_currency`);
* **`types`** and **`transactions`**, the combinations for which the field exists. Outside of these, the field is ignored and signaled in `warnings[]`;
* **`values`**, the allowed codes, with labels. When they are missing, `values_from` shows where they are (for example `levels` or `currencies`);
* **`values_by_type`**, when the allowed values differ from one property type to another (for example, the construction materials of a warehouse compared to those of a house).

The vocabulary does not specify which fields are mandatory; these rules are in [Fields of a listing](/en/guides/listing-payload). The safest test remains `POST /listings/validate`.

## Retired codes

A code never disappears. When a code changes, the old one goes into `retired`, with its successor:

```json theme={null}
{ "kind": "value:partitioning", "code": "decomandat", "replaced_by": "detached", "retired_on": "2026-10-17" }
```

* `kind` tells what kind of code it is: `feature`, `subtype`, `field` (a renamed field) or `value:<câmp>` (a value of a field).
* If you submit the old code, Housera reads it as the successor. You lose nothing and do not receive an error.
* In responses, you always receive the new code. Update your mapping when you see one of your codes in `retired`.

## Language of labels

`locale=ro` (default) or `locale=en` only changes the labels (`label`). **Codes are never translated**: `apartment` remains `apartment` in any language.

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

## Cache

The vocabulary changes rarely. The response has the header `ETag` and can be cached for one hour. To cheaply check if it has changed, send the `ETag` received in `If-None-Match`:

```bash theme={null}
curl -i "https://housera.ro/api/v1/schema" \
  -H 'If-None-Match: "919efa73ab07e521d4f92bbc2e5b65f0"'
```

If nothing has changed, you receive `304 Not Modified`, without a body.

The limit for `GET /schema` is 60 requests per minute per IP address, separate from your keys' limit.


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