XML feed for listing import

How to prepare an XML feed for importing listings into Realistimo. For on-demand sync see the REST API.

Overview

XML (this page)

What to publish in the feed and how import reads the fields.

REST

API key, POST /start, POST /latest-log, limits, and optional callback.

Tutorial

Get started

Copy the minimal example below, or download a fuller sample XML.
Set agency_uid to the source id Realistimo gave your agency, and broker_id values to agent source ids already linked in Realistimo.
Add offers with a stable offer_uid, category/subcategory, location (internal_id), images, price, description, currency=eur.
Host the feed on a public HTTPS URL and send it to [email protected].
For manual sync: REST tutorial.

Geo lookup files: CSV · PostgreSQL dump

Explanation

How synchronisation works

Feed level: <updated> is the feed version. If it is unchanged since the last successful sync, the import is skipped.
Stale feed: if <updated> parses as a date older than 30 days, processing stops.
Offer level: for a published offer, if <last_update> is present and not newer than the last imported change, most offer fields are skipped (price, agent assignment, and description still update). Empty/missing <last_update> does not trigger that skip.
Missing offers: offers absent from the feed are taken down/archived on a normal import run.
Missing optional XML tags are treated as empty — you do not need every optional tag.

“Required” below means: without a value, import/publish usually fails or the offer stays unpublished. Many attributes have default values.

How-to

How to prepare a feed

Root <feed>, brokers in <Brokers>, offers in <offers>.
Location: internal_id for the city, village, or neighborhood from the geo files. Without it the location is looked up in the description; if not found, the offer stays unpublished.
Currency: send eur.
On every real change, bump feed <updated> and <last_update> on affected offers.
The URL must be reachable by server-side clients (no interactive Cloudflare challenge).

Reference

Minimal example

Copy this skeleton, replace placeholders, and set current timestamps (YYYY-MM-DD HH:MM:SS, not older than 30 days).

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <updated>YYYY-MM-DD HH:MM:SS</updated>
  <agency_uid>YOUR_AGENCY_SOURCE_ID</agency_uid>
  <Brokers>
    <Broker>
      <BrokerID>YOUR_AGENT_SOURCE_ID</BrokerID>
      <BrokerName>Ivan Ivanov</BrokerName>
      <BrokerPhone>0888000000</BrokerPhone>
      <BrokerEmail>[email protected]</BrokerEmail>
    </Broker>
  </Brokers>
  <offers>
    <offer>
      <offer_uid>offer-1</offer_uid>
      <last_update>YYYY-MM-DD HH:MM:SS</last_update>
      <description>Test listing</description>
      <images>https://example.com/a.jpg</images>
      <price>100000</price>
      <surface>70</surface>
      <currency>eur</currency>
      <category>продажби</category>
      <subcategory>2-СТАЕН</subcategory>
      <internal_id>8545</internal_id>
      <broker_id>YOUR_AGENT_SOURCE_ID</broker_id>
    </offer>
  </offers>
</feed>

Download fuller sample XML (shape reference — still replace ids, timestamps, and content with yours).

Agency

Tag	Description	Notes
`<updated>`	Feed version / date	Required Must change when content changes; max 30 days old
`<agency_uid>`	Agency source id	Required Must match the id configured for your agency
`<agency_name>`, `<agency_phone>`, `<agency_email>`	Metadata	Optional Not used by import; safe for compatibility
`<result_url>`	Callback after import	Optional Realistimo POSTs a latest-log-shaped JSON body; see REST

Brokers

<Brokers>/<Broker> provides broker contact details for the feed. Offer broker_id must match an agent source id already linked to your agency in Realistimo (set up during integration). The XML BrokerID values should use the same ids. An offer whose broker_id doesn't match a linked agent is not imported, unless the agency has a fallback agent configured.

Tag	Notes
`<BrokerID>`	Required Agent source id (prefer ≠ `agency_uid`)
`<BrokerName>`	Required Name (+ surname)
`<BrokerPhone>`, `<BrokerEmail>`, `<BrokerPhoto>`	Optional

Offers (supported fields)

Tag	Description	Notes
`<last_update>`	Offer change time	Recommended Date/time or unix timestamp. When present and not newer than the last imported change, most fields are skipped on published offers
`<offer_uid>`	Stable id	Required Do not change on edits
`<offer_code>`	Reference code	Optional
`<title>`	Title fragment	Optional Separate from description
`<description>`	Description	Recommended Strongly desired for publication
`<images>`	URLs	Required Separator `;`
`<price>`	Price	Required Digits only, no thousands separator: everything after the first comma or period is cut off (`100,000` imports as 100). Spaces are fine. `0` or `1` = “Price negotiable”. Zeroed for parent construction/complex
`<surface>`	Area m²	Required Required for most types. Garage and parking space default to 18 m² when the area is missing. For land see plot and land
`<surface_parcel>`	Yard/parcel	Optional Yard area in m². Used as the property's area too when `surface` is missing
`<currency>`	Currency	Required `eur`. If it is missing, the price is shown at almost half its value.
`<category>`	`продажби` / `наеми`	Required
`<subcategory>`	Property type	Required Must be an exact supported value (see below)
`<internal_id>`	Geo internal id	Required id for the city, village, or neighborhood from the geo files. If missing or wrong, the location is looked up in the description; if not found, the offer stays unpublished
`<subregion_id>`	Mapped location id	Optional Used only by some legacy integrations. Don't rely on it — send `internal_id`
`<construction_type>`	епк / панел / тухла / гредоред	Optional Lowercase only, see values
`<floor>`, `<floorAll>`	Floor / floors	Optional `floor` value `0` is ignored
`<building_condition>`	Construction stage	Optional See values
`<build_year>`	YYYY-MM-DD / YYYY	Optional Full date or year only (`2005`). A year on its own is accepted from 1800 to 10 years ahead and ignored otherwise. Older buildings display as a period (“Before 1989” or “Between 1990 and 2004”)
`<furnished>`	0 / 14 / 23 / 65	Optional `14` = furnished, `65` = semi furnished, `0` and `23` = unfurnished. A missing or other value is recorded as “Not sure”, even if the description says “furnished” — so always send this tag
`<heating_ids>`	IDs via `,`	Optional 4, 6, and 18 = solid fuel, 35 = AC, 44 = electricity, 46 = city central heating, 80 = gas. Other ids are ignored
`<parking_ids>`	52, 93	Optional 52 = garage, 93 = parking space. Other ids are ignored
`<rooms_count>`, `<bedroom_count>`, `<bath_count>`	Counts	Optional See default values
`<exterior_ids>`	IDs via `,`	Optional 42 = elevator, 10 = asphalt road. Other ids are ignored
`<broker_id>`	Agent source id	Required Must match an agent linked in Realistimo
`<construction_id>`	Parent offer_uid	Optional See building/complex how-to
`<youtube_link>` / `<youTube_link>`	YouTube	Optional
`<virtual_panorama_link>`	Virtual tour	Optional Links from Matterport, Giraffe360, CloudPano, Panoee, imot360, Zelanos, Renderimo, Webobook, and Kuula (bit.ly short link) are recognized. Other links are skipped without blocking publication
`<Exclusive>`	0/1	Optional

Values

subcategory (supported values)

СТАЯ, АПАРТАМЕНТ, ЕДНОСТАЕН, БОКСИОНЕРА, СТУДИО, 1-СТАЕН, 2-СТАЕН, 3-СТАЕН, 4-СТАЕН, МНОГОСТАЕН, МЕЗОНЕТ, ГАРСОНИЕРА, ГАРСОНИЕРА ЛУКС
АТЕЛИЕ · АТЕЛИЕ, ТАВАН · ТАВАН · ЕТАЖ ОТ КЪЩА · КЪЩА · ВИЛА
ОФИС, МАГАЗИН, ТЪРГОВСКИ ОБЕКТ, ЗАВЕДЕНИЕ, СПОРТ, САЛОН ЗА КРАСОТА, СКЛАД, ГАРАЖ, ПАРКОМЯСТО, ПРОМ. ПОМЕЩЕНИЕ, ХОТЕЛ
БИЗНЕС ИМОТ, ДРУГО — business property
ПАРЦЕЛ, ЗЕМЕДЕЛСКА ЗЕМЯ — see plot and land
СГРАДИ, СГРАДА — whole building with price (not a parent for construction_id)
НОВА СГРАДА, СГРАДА НОВО СТРОИТЕЛСТВО — parent construction
ЗАТВОРЕН КОМПЛЕКС — parent complex

Send values exactly as listed, in capital letters. An unknown value stops the offer's import.

building_condition

Completed (or bds-completed) — With Act 16
SemiCompleted (or semi_completed) — With Act 15
NotCompleted (or not_completed) — With Act 14
UnderConstruction — Under construction/with building permit
PreConstruction (or pre_construction) — On the green (conceptual project)

Case matters.

construction_type

епк — EPC (creeping formwork)
панел — Panel
тухла — Brick
гредоред — Half timber

Lowercase only: Тухла is not recognized.

Default values

When a tag is missing or empty, import records:

Tag	Default value
`<heating_ids>`	Electricity
`<rooms_count>`	For an apartment — based on `subcategory` (`2-СТАЕН` = 2), otherwise 1
`<bedroom_count>`	Room count minus 1, at least 1
`<bath_count>`	1, but not more than the room count
`<building_condition>`	With Act 16
`<construction_type>`	Not sure (sale only)
`<furnished>`	Not sure (all types)
`<surface>`	The area from the description, if stated there; garage and parking space default to 18 m²

Heating, rooms, bedrooms, bathrooms, construction stage, and construction type are not populated for plots, agricultural land, garages, parking spaces, or new construction.

Ignored tags

These tags are not applied during import. They may appear in the feed but have no effect on the offer: balcony_count, land_category, parcel_in_regulation, new_construction.

How-to

Building / complex → apartments

Parent: subcategory is one of НОВА СГРАДА, СГРАДА НОВО СТРОИТЕЛСТВО, ЗАТВОРЕН КОМПЛЕКС.
Child: <construction_id>PARENT_OFFER_UID</construction_id>.
Order in XML does not matter. Empty tag clears the link. Self-ref / invalid parent is ignored.

Plot and land

There are no separate tags for a plot — it is submitted like a regular offer:

<subcategory>ПАРЦЕЛ</subcategory> for a building plot, or ЗЕМЕДЕЛСКА ЗЕМЯ for agricultural land. Forest, vineyard, pasture, and orchard can't be submitted yet.
<surface> is the property area in m². A value between 0 and 1 is read as decares: 0.8 = 800 m² (with a period, not a comma). If surface is missing, surface_parcel is used, then the area from the description.
<internal_id> for the city or village is enough — a neighborhood is not required.
Rooms, floor, construction type, and furnishing are not needed.
Asphalt road: <exterior_ids>10</exterior_ids>. There are no tags for electricity and water — write exactly “ток и вода на граница” in the (Bulgarian) description (or just “ток на граница” / “вода на граница”). Other wordings may not be recognized.
The intended use is also read from the description. If it is not stated there, a ПАРЦЕЛ gets both “Residential building” and “Commercial building”, while for ЗЕМЕДЕЛСКА ЗЕМЯ the field stays empty.
land_category and parcel_in_regulation are ignored.

<offer>
  <offer_uid>parcel-1</offer_uid>
  <last_update>YYYY-MM-DD HH:MM:SS</last_update>
  <title>Парцел в село Лозен</title>
  <description>Равен парцел с лице към улица. Ток и вода на граница.</description>
  <images>https://example.com/p1.jpg;https://example.com/p2.jpg</images>
  <price>85000</price>
  <surface>1200</surface>
  <currency>eur</currency>
  <category>продажби</category>
  <subcategory>ПАРЦЕЛ</subcategory>
  <internal_id>9433</internal_id>
  <exterior_ids>10</exterior_ids>
  <broker_id>YOUR_AGENT_SOURCE_ID</broker_id>
</offer>