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 preferred), 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: prefer internal_id from the geo DB; alternative is subregion_id.
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.

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 Integer part; zeroed for parent construction/complex
`<surface>`	Area m²	Required Required for most types (except garage)
`<surface_parcel>`	Yard/parcel	Optional
`<currency>`	Currency	Recommended eur Accepted: `eur`/`EUR`/`BGN`/`лв` — normalized to EUR. Missing currency is treated as BGN and converted to EUR. Prefer `eur`
`<category>`	`продажби` / `наеми`	Required
`<subcategory>`	Property type	Required Must be an exact supported value (see below)
`<internal_id>`	Geo internal id	Recommended Preferred location method
`<subregion_id>`	Mapped location id	Optional Used when `internal_id` is missing/not numeric
`<construction_type>`	епк / панел / тухла / гредоред / метална конструкция	Optional
`<floor>`, `<floorAll>`	Floor / floors	Optional `floor` value `0` is ignored
`<building_condition>`	Completed / …	Optional
`<build_year>`	YYYY-MM-DD	Optional
`<furnished>`	0/14/23/65	Optional 0 and 23 = unfurnished
`<heating_ids>`	IDs via `,`	Optional 4/6/18 pellets, 35 AC, 44 electricity, 46 district, 80 gas
`<parking_ids>`	52, 93	Optional 52 garage, 93 parking space
`<rooms_count>`, `<bedroom_count>`, `<bath_count>`	Counts	Optional
`<exterior_ids>`	42=elevator, 10=asphalt	Optional Only these ids are applied
`<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>`	Tour	Optional
`<Exclusive>`	0/1	Optional

Values

subcategory (supported values)

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

Send values exactly as listed (Cyrillic). Unknown values cause the offer import to fail.

building_condition

Completed, UnderConstruction, PreConstruction, SemiCompleted, NotCompleted.

construction_type

епк, панел, тухла, гредоред, метална конструкция.

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.