# TopBroker Open Property Feed — version 1

One self-describing feed of real-estate listings, served in two encodings of the
same document: JSON (canonical) and XML. Every document opens with a `vocabulary`
legend defining every code it uses, so no second lookup is ever required.

JSON Schema: https://api.topbroker.lt/spec/v1/property.json

## How to read a document

1. Read `vocabulary` first. It defines every code appearing below it, with a
   Lithuanian label, an English label and a definition.
2. Read `properties`. Each entry is one listing.
3. A key that is absent is not stated. We omit rather than send empty values.

## Rules that matter

- **Absence means delist.** The feed is the complete current set of published
  listings. A listing that was present yesterday and is absent today has been
  sold, archived or withdrawn, and must be removed from your site.
- **All areas are square metres.** Every `*_m2` field is already converted.
- **Presence is the flag.** `sale` present means the property is for sale;
  `rent` present means it is for rent. Both may be present. There is no separate
  boolean.
- **Hidden locations are omitted, not flagged.** When an agency withholds an
  exact address, `location.precision` is `district` and the street, building
  number and coordinates are simply absent. You are never asked to hide
  something we sent you.
- The document is regenerated hourly. `generated_at` is on the root,
  `updated_at` on each listing.


## Property kinds

- `apartment` — Apartment (lt: Butas). A self-contained dwelling unit within a multi-unit residential building.
- `house` — House (lt: Namas). A detached, semi-detached or terraced house, cottage or homestead, sold together with the land it stands on.
- `land` — Land (lt: Sklypas). An undeveloped land parcel. Its `area_m2` is the parcel itself.
- `commercial` — Commercial premises (lt: Komercinės patalpos). Non-residential premises - office, retail, warehouse, catering, manufacturing or service space. Aruodas calls this category "premises".
- `garage` — Garage (lt: Garažas). A garage or parking structure. A property stored as a house whose form is a garage is published under this kind too.


## Fields

- `id` (string, required) — Stable identifier for this listing. Use it to match a listing you already hold; it changes only when the broker deliberately relists the property under a new identity.
- `kind` (enum, required) — The category of property. Determines which other fields are present. Codes: `kinds`.
- `kind_label` (i18n_string, optional) — The agency's own name for this category. A display hint only — never key on it, agencies rename these freely.
- `status` (enum, required) — Availability of the listing. Sold and archived properties are never present in the feed at all. Codes: `status`.
- `updated_at` (datetime, required) — When this listing last changed, ISO 8601 with offset. Diff against your stored copy to find what moved since the last fetch.
- `title` (string, recommended) — Short human-readable headline for the listing.
- `descriptions` (array, recommended) — Free-text descriptions, one entry per language. Plain text; no markup.
- `descriptions.locale` (string) — ISO 639-1 language code, e.g. "lt" or "en".
- `descriptions.content` (string) — The description body.
- `sale` (object, conditional) — Present if and only if the property is for sale. Its presence IS the for-sale flag; there is no separate boolean.
- `sale.price` (money) — Asking price.
- `sale.price_per_m2` (money) — Asking price divided by area_m2, as quoted by the agency.
- `rent` (object, conditional) — Present if and only if the property is for rent. Its presence IS the for-rent flag.
- `rent.price` (money) — Rent per period.
- `rent.price_per_m2` (money) — Rent divided by area_m2, as quoted by the agency.
- `rent.period` (enum) — The unit the rent price is quoted in. Never assume monthly. Codes: `rent_period`.
- `location` (object, required) — Where the property is. Keys are OMITTED, not blanked, when the agency has chosen to hide the exact location — you will never be asked to hide something we sent you.
- `location.precision` (enum) — How precisely this location is disclosed. Codes: `location_precision`.
- `location.municipality` (string) — Municipality (savivaldybė).
- `location.city` (string) — City or settlement.
- `location.district` (string) — District or neighbourhood within the city.
- `location.street` (string) — Street name. Omitted when precision is "district".
- `location.building_number` (string) — House or building number. Omitted when precision is "district".
- `location.coordinates` (object) — WGS84 latitude and longitude. Omitted entirely when precision is "district".
- `location.coordinates.lat` (decimal) — Latitude in WGS84 decimal degrees.
- `location.coordinates.lon` (decimal) — Longitude in WGS84 decimal degrees.
- `area_m2` (decimal, m2, required) — Usable floor area in SQUARE METRES. Always m², regardless of the unit the agency quotes internally.
- `rooms` (integer, recommended) — Number of rooms.
- `floor` (integer, recommended) — Which floor the unit is on. Negative values are basement levels. Absent when the floor is not stated.
- `floors_total` (integer, recommended) — Number of floors in the building.
- `year_built` (integer, recommended) — Year the building was completed.
- `year_renovated` (integer, optional) — Year of the most recent major renovation, if any.
- `building` (object, recommended) — Properties of the building the unit sits in.
- `building.structure` (enum) — Construction type of the building. Codes: `building_structure`.
- `building.form` (enum) — The form of house - detached, semi-detached, townhouse, homestead and so on. Present for houses only. Codes: `building_form`.
- `building.heating` (enum) — How the unit is heated. Codes: `building_heating`.
- `building.condition` (enum) — Fit-out and repair state of the unit. Codes: `building_condition`.
- `building.energy_class` (enum) — EU energy performance certificate class. Codes: `energy_class`.
- `building.windows` (enum) — Window frame material. Codes: `window_type`.
- `features` (enum_set, optional) — Amenities present. An unlisted code means "not stated", not "absent". Codes: `features`.
- `land_area_m2` (decimal, m2, recommended) — Area of the land parcel belonging to a house, in SQUARE METRES. For a `land` property the parcel area is `area_m2` itself and this field is absent.
- `area_from_m2` (decimal, m2, optional) — Smallest area available, in SQUARE METRES, when commercial premises can be divided into units.
- `area_to_m2` (decimal, m2, optional) — Largest area available, in SQUARE METRES, when commercial premises can be divided into units.
- `floors_from` (integer, optional) — Lowest floor the offered commercial premises occupy.
- `floors_to` (integer, optional) — Highest floor the offered commercial premises occupy.
- `purposes` (enum_set, recommended) — Permitted or intended uses. Present for land and commercial premises, which routinely carry more than one. Codes: `purposes`.
- `garage` (object, optional) — Garage detail. Present for a garage, and for a house that includes one. Note this is a FIELD named garage; the property kind of the same name is separate.
- `garage.type` (enum) — Construction type of the garage. Codes: `garage_type`.
- `garage.cars_fit` (integer) — How many cars fit.
- `media` (array, recommended) — Photos, video and virtual tours, in the order the agency arranged them.
- `media.type` (enum) — What kind of media this is. Codes: `media_type`.
- `media.url` (string) — Absolute URL.
- `media.position` (integer) — Display order for photos, ascending.
- `media.provider` (string) — Hosting provider for a virtual tour, e.g. "matterport".
- `contact` (object, required) — The agent handling this listing. Always an agent, never the property owner.
- `contact.name` (string) — Agent's full name.
- `contact.email` (string) — Agent's email address.
- `contact.phone` (string) — Agent's phone number in international format.


## Vocabularies

### building_condition

- `fully_equipped` — Fully finished / Visa apdaila. Fully finished and ready to occupy.
- `partially_equipped` — Partially finished / Dalinė apdaila. Partially finished; some fit-out work remains.
- `renovated` — Renovated / Suremontuotas. Recently renovated.
- `good_condition` — Good condition / Tvarkingas. Sound and habitable, not recently renovated.
- `needs_renovation` — Needs renovation / Remontuotinas. Requires renovation before comfortable occupation.
- `other` — Other / Kita. None of the above.
- `shell` — Shell / Neiųrengtas/Statomas. Weather-tight shell, unfinished inside, or still under construction.
- `unfinished` — Unfinished / Neiųrengtas. Not fitted out.

### building_form

- `house` — Detached house / Namas. A free-standing single house.
- `semi_detached` — Semi-detached / Sublokuotas. A house blocked together with one or more neighbours.
- `house_share` — Part of a house / Namo dalis. A share of a house rather than the whole building.
- `townhouse` — Townhouse / Kotedžas. A townhouse or cottage in a terrace.
- `homestead` — Homestead / Sodyba/Vasarnamis. A rural homestead or summer house.
- `garden_house` — Garden house / Sodo namas. A house in a garden association, often seasonal.
- `other` — Other / Kita. None of the above.

### building_heating

- `central` — Central / Centrinis. Building-wide central heating.
- `district` — District / Centrinis kolektorinis. Municipal district heating delivered through a shared collector.
- `gas` — Gas / Dujinis. Individual gas boiler.
- `electric` — Electric / Elektrinis. Electric heating.
- `solid_fuel` — Solid fuel / Kietu kuru. Wood, pellet or coal fired.
- `geothermal` — Geothermal / Geoterminis. Ground-source heat pump.
- `liquid_fuel` — Liquid fuel / Skystu kuru. Oil or other liquid fuel fired.
- `aerothermal` — Aerothermal / Aeroterminis. Air-source heat pump.
- `other` — Other / Kita. None of the above.

### building_structure

- `panel` — Panel / Blokinis. Prefabricated concrete panel or block construction, not brick.
- `brick` — Brick / Mūrinis. Brick or masonry construction.
- `monolithic` — Monolithic / Monolitas. Cast-in-place reinforced concrete.
- `wood` — Wood / Medinis. Timber construction.
- `timber_frame` — Timber frame / Karkasinis. Frame construction with non-loadbearing infill.
- `log` — Log / Rąstinis. Log construction.
- `metal` — Metal / Metalinis. Metal frame or hangar construction.
- `other` — Other / Kita. None of the above.

### energy_class

- `a++` — A++ / A++. EU energy performance class A++
- `a+` — A+ / A+. EU energy performance class A+.
- `a` — A / A. EU energy performance class A.
- `b` — B / B. EU energy performance class B.
- `c` — C / C. EU energy performance class C.
- `d` — D / D. EU energy performance class D.
- `e` — E / E. EU energy performance class E.
- `f` — F / F. EU energy performance class F.
- `g` — G / G. EU energy performance class G

### features

- `air_conditioning` — Air conditioning / Kondicionavimas. Air conditioning installed. _(apartment, house, commercial)_
- `alarm_system` — Alarm system / Signalizacija. Burglar alarm installed. _(apartment, house, commercial)_
- `attic` — Attic / Yra palėpė. The building has an attic. _(apartment)_
- `attic_unit` — Located in attic / Butas palėpeje. The unit itself is in the attic. _(apartment)_
- `automatic_gate` — Parking gates / Automatiniai vartai. Automatic entrance gate. _(garage)_
- `balcony` — Balcony / Balkonas. Has a balcony. _(apartment, commercial)_
- `basement` — Basement / Rūsys. Has a basement or cellar. _(apartment, house, garage)_
- `bath` — The bathroom / Vonia. Bathtub in the bathroom. _(apartment, house)_
- `bathhouse` — Bathouse / Pirtis. Separate bathhouse or sauna building. _(house)_
- `border_plot` — Border plot / Kraštinis sklypas. The plot is on the edge of its block. _(house, land)_
- `cable_tv` — Cable TV / Kabelinė televizija. Cable television connection available. _(apartment, house)_
- `canteen_in_building` — Cafeteria / Maitinimo įstaiga pastate. Cafeteria or canteen in the building. _(commercial)_
- `cargo_elevator` — Cargo elevator / Krovininis liftas. The building has a goods lift. _(commercial)_
- `cctv` — Video cameras / Vaizdo kameros. Video surveillance covering the property. _(apartment)_
- `closed_yard` — Closed yard / Uždaras kiemas. Enclosed or gated courtyard. _(apartment)_
- `conference_hall` — Conference hall / Konferencijų salė pastate. Conference hall in the building. _(commercial)_
- `detailed_plan` — Floor plan / Detalus planas. A detailed territorial plan has been approved. _(apartment, house, land, commercial)_
- `dish_washer` — Dish Washer / Indaplovė. Dishwasher included. _(apartment)_
- `double_glazing` — Windows with double glazing / Langai su stiklo paketais. Double- or triple-glazed windows. _(apartment, house)_
- `dressing_room` — Cloakroom / Rūbinė. Separate dressing room or walk-in wardrobe. _(apartment, house)_
- `electricity` — Electricity / Elektra. Electricity is connected. _(house, land, commercial)_
- `elevator` — Elevator / Liftas. The building has a passenger lift. _(apartment, house, commercial)_
- `fireplace` — Fireplace / Židinys. Fireplace or wood stove. _(apartment, house)_
- `furniture` — With furniture / Su baldais. Sold or let furnished. _(apartment, house, commercial)_
- `gas` — Gas / Dujos. Gas is connected. _(apartment, house, land, commercial)_
- `good_access` — Good access / Geras privažiavimas. Convenient vehicle access. _(house, commercial)_
- `heat_recovery_ventilation` — Recuperation system / Rekuperacinė sistema. Mechanical ventilation with heat recovery. _(apartment)_
- `heated_floors` — Heated floors / Šildomos grindys. Underfloor heating. _(apartment)_
- `heating` — Heating / Šildymas. The space is heated. _(garage)_
- `high_ceiling` — High ceiling / Aukštos lubos. Ceilings noticeably higher than standard. _(apartment)_
- `inspection_pit` — Pit / Duobė. Has a vehicle inspection pit. _(garage)_
- `internet` — Internet / Internetas. Internet connection available. _(apartment, house, land, commercial)_
- `kitchen` — Household appliances / Buitinė technika. Has a separate kitchen. _(apartment, house, commercial)_
- `kitchen_furniture` — Equipped kitchen / Virtuvės komplektas. Fitted kitchen units included. _(apartment)_
- `landline` — Telephone line / Telefono linija. Landline telephone connection. _(apartment, house, land, commercial)_
- `local_sewerage` — Local sewage / Vietinė kanalizacija. Local septic or treatment system. _(house)_
- `mains_sewerage` — City sewage / Miesto kanalizacija. Connected to municipal sewerage. _(house)_
- `near_forest` — Near forest / Šalia miško. Adjoins or is close to forest. _(house, land)_
- `near_water` — Has access to water lake / Šalia vandens telkinio. Close to a lake, river or the sea. _(house, land)_
- `new_electricity` — New electricity installation / Nauja elektros instaliacija. Electrical installation recently renewed. _(apartment)_
- `new_sewerage` — New sewerage / Nauja kanalizacija. Sewerage recently renewed. _(apartment)_
- `open_kitchen` — Kitchen connected with  sitting - room / Virtuvė sujung. su kamb.. Kitchen open to the living area. _(apartment, house)_
- `parking` — Parking space / Vieta automobiliui. Parking space available. _(apartment, commercial)_
- `parquet` — Parquet / Parketas. Parquet flooring. _(apartment, house)_
- `partial_unit` — Part of an apartment / Buto dalis. Only part of the unit is offered. _(apartment)_
- `paved_access` — Good road access / Patogus privažiavimas. Reached by a paved road. _(land)_
- `plastic_plumbing` — Plastic plumbing / Plastikiniai vamzdžiai. Plumbing renewed with plastic piping. _(apartment, house)_
- `refrigerator` — Fridge / Šaldytuvas. Refrigerator included. _(apartment, house)_
- `reinforced_door` — Armored door / Šarvuotos durys. Reinforced security entrance door. _(apartment, house)_
- `residence_registration` — Place of recidence / Galima deklaruoti gyv. vietą. Residence may be registered at this address. _(apartment)_
- `sauna` — Bathouse / Pirtis. Private sauna. _(apartment)_
- `secured_stairwell` — Staircase with coded lock / Kodinė laiptinės spyna. Stairwell locked by key or code. _(apartment)_
- `security` — Security / Apsauga. Guarded, or covered by a security service. _(apartment, commercial, garage)_
- `separate_entrance` — Dedicated entrance / Atskiras įėjimas. Has its own separate entrance. _(apartment, commercial)_
- `separate_toilet` — WC and bathroom separated / Tualetas ir vonia atskirai. Toilet separate from the bathroom. _(apartment, house)_
- `sewerage` — Plumbing / Kanalizacija. Sewerage is available. _(land)_
- `shower` — Shower / Dušas. Shower in the bathroom. _(apartment, house, commercial)_
- `storage_room` — Warehouse / Sandėliukas. Dedicated storage room. _(apartment)_
- `stove` — Stove / Viryklė. Cooker or hob included. _(apartment)_
- `street_entrance` — Street Entrance / Įėjimas iš gatvės. Entrance directly from the street. _(commercial)_
- `swimming_pool` — Waterpool / Baseinas. Has a swimming pool. _(house)_
- `terrace` — Balcony or terrace / Balkonas/Terasa. Has a terrace or balcony. _(apartment, house)_
- `three_phase_electricity` — Electricity 3x380V / Elektra 3x380V. Three-phase 380V electricity supply. _(house)_
- `tv_connection` — TV / Televizorius. Television connection available. _(apartment, house)_
- `two_level` — Apartment over several floors / Butas per kelis aukštus. The unit spans two floors. _(apartment)_
- `washing_machine` — Washing machine / Skalbimo mašina. Washing machine included. _(apartment, house)_
- `water` — Water / Vandentiekis. Mains or well water is connected. _(house, land, commercial, garage)_
- `water_boiler` — Hot water boiler / Boileris. Hot water boiler installed. _(house)_

### garage_type

- `brick` — Brick / Mūrinis. Brick or masonry garage.
- `metal` — Metal / Geležinis. Prefabricated metal garage.
- `underground` — Underground / Požeminis. Underground parking.
- `multi_storey` — Multi-storey / Daugiaaukštis. A space in a multi-storey car park.
- `other` — Other / Kita. None of the above.

### kinds

- `apartment` — Apartment / Butas. A self-contained dwelling unit within a multi-unit residential building.
- `house` — House / Namas. A detached, semi-detached or terraced house, cottage or homestead, sold together with the land it stands on.
- `land` — Land / Sklypas. An undeveloped land parcel. Its `area_m2` is the parcel itself.
- `commercial` — Commercial premises / Komercinės patalpos. Non-residential premises - office, retail, warehouse, catering, manufacturing or service space. Aruodas calls this category "premises".
- `garage` — Garage / Garažas. A garage or parking structure. A property stored as a house whose form is a garage is published under this kind too.

### location_precision

- `exact` — Exact / Tikslus. Full address and coordinates are disclosed.
- `district` — District / Rajonas. The agency has withheld the exact location. Street, building number and coordinates are omitted from this listing.

### media_type

- `photo` — Photo / Nuotrauka. A still image of the property.
- `video` — Video / Vaizdo įrašas. A video walkthrough.
- `tour` — Virtual tour / 3D turas. An interactive 3D or 360-degree tour.

### purposes

- `residential` — Residential / Namų valda. Residential homestead plot. _(land)_
- `multi_storey_residential` — Multi-storey residential / Daugiaaukštė gyvenamoji. Zoned for multi-storey housing. _(land)_
- `agricultural` — Agricultural / Žemės ūkio. Farmland. _(land)_
- `forestry` — Forestry / Miškų. Forest land. _(land)_
- `garden` — Garden / Sodų. Land in a garden association. _(land)_
- `commercial_land` — Commercial / Komercinė. Zoned for commercial development. _(land)_
- `industrial` — Industrial / Pramoninė. Zoned for industry. _(land)_
- `storage` — Storage / Sandėliavimo. Zoned for warehousing. _(land)_
- `recreational` — Recreational / Rekreacinės. Zoned for recreation. _(land)_
- `office` — Office / Administracinės. Office use. _(commercial)_
- `retail` — Retail / Prekybos. Retail or trade use — shops and other customer-facing commerce. _(commercial)_
- `warehouse` — Warehouse / Sandėliavimo. Warehousing and storage use, not a shop. _(commercial)_
- `catering` — Catering / Maitinimo. Restaurant, cafe or other catering use. _(commercial)_
- `services` — Services / Paslaugų. Service-industry use. _(commercial)_
- `hospitality` — Hospitality / Viešbučių. Hotel or guest accommodation use. _(commercial)_
- `manufacturing` — Manufacturing / Gamybinės. Manufacturing use. _(commercial)_
- `whole_building` — Whole building / Pastatas. The entire building is offered rather than individual premises. _(commercial)_
- `other` — Other / Kitos paskirties. A use not covered by the codes above. _(land, commercial)_

### rent_period

- `month` — Per month / Per mėnesį. Rent is quoted per calendar month.
- `night` — Per night / Per parą. Rent is quoted per night — a short-term listing.

### status

- `available` — Available / Laisvas. On the market and not reserved.
- `reserved` — Reserved / Rezervuotas. Reserved by a prospective buyer or tenant but not yet sold. Still advertised. No detail about the reservation is disclosed.

### window_type

- `wood` — Wooden / Mediniai. Wooden window frames.
- `plastic` — PVC / Plastikiniai. PVC window frames.
- `aluminium` — Aluminium / Aliuminiai. Aluminium window frames.
- `glass_block` — Glass block / Stiklo blokeliai. Glass block glazing.


## What this feed deliberately never contains

The feed is an allowlist: only the fields above can ever appear. It carries no
property owners, no broker commission, no free-form internal custom fields, no
transaction or negotiation history, no buyer identities, no viewing records and
no internal task or pipeline data. `contact` is always the listing agent, never
an owner.

Sold and archived listings are removed from the feed entirely rather than
published with a status, so `status` has exactly two values: `available` and
`reserved`. A reserved listing discloses no detail about the reservation.