Autoload XML-file format description

1. XML-file sample

<?xml version="1.0" encoding="UTF-8"?>
<objects>
   <object>
      <id>123456</id>
      <edited>2020-01-17T08:05:33+0000</edited>
      <description>
         <ru><![CDATA[Описание объекта]]></ru>
         <en><![CDATA[Object description]]></en>
      </description>
      <excerpt>
         <ru><![CDATA[Краткое описание объекта]]></ru>
         <en><![CDATA[Short object description]]></en>
      </excerpt>
      <labels>
         <ru>
            <label><![CDATA[Метка 1]]></label>
            <label><![CDATA[Метка 2]]></label>
         </ru>
         <en>
            <label><![CDATA[Label 1]]></label>
            <label><![CDATA[Label 2]]></label>
         </en>
      </labels>
      <deal>1</deal>
      <price>123456</price>
      <currency>EUR</currency>
      <price_period>monthly</price_period>
      <installment>1</installment>
      <type>1</type>
      <region>90</region>
      <district>1</district>
      <status>1</status>
      <square>150</square>
      <rooms>2</rooms>
      <bedrooms>1</bedrooms>
      <bathrooms>2</bathrooms>
      <floor>5</floor>
      <floors>10</floors>
      <tosea>500</tosea>
      <tocenter>1000</tocenter>
      <toairport>15</toairport>
      <finish>
         <year>2021</year>
         <quarter>1</quarter>
      </finish>
      <finished>0</finished>
      <geo>
         <lat>30.123456</lat>
         <lng>31.234567</lng>
      </geo>
      <developer>83</developer>
      <images>
         <image>http://domain.com/images/image1.jpg</image>
         <image>http://domain.com/images/image2.jpg</image>
         <image>http://domain.com/images/image3.jpg</image>
      </images>
      <agent>
         <name>John Smith</name>
      </agent>
      <features>
         <feature>5</feature>
         <feature>19</feature>
         <feature>71</feature>
      </features>
   </object>
</objects>

Sample XML-file is also available at: https://turk.estate/uploads/xml_import_sample.xml

 

2. General description

Objects import file should be a UTF-8 encoded valid XML file. File should be available by the specified URL without any specific parameters (e.g. authorization, specific HTTP headers).

Attention: 30 seconds timeout is set for the file upload, your server response and file download time should not exceed this value.

Root XML tag – objects

The set of objects is specified by the list of object tags.

 

3. Fields description

Available tags and their descriptions are enlisted below.

Numbers are specified without any spaces or separators, except for the decimal point. For the decimal point the point symbol should be used.

Attention: tags should not contain HTML or any other code.

TagDescriptionObligatory

id

 Unique object identifier. Can contain numbers and letters. Yes

edited

 Object last edit date and time in ISO-8601 format Yes

description

Object description. Should be wrapped in <![CDATA[ ]]>

Example:

<description><![CDATA[Object description]]></description>

Supports multilingual format. In this case represents a list of tags with the language code (see p. 4) as the tag name and the object description in this language as value. Object description should be wrapped in <![CDATA[ ]]>.

Example:

<description>
   <ru><![CDATA[Описание объекта]]></ru>
   <en><![CDATA[Object description]]></en>
</description>
 No

excerpt

Short object description. Should be wrapped in <![CDATA[ ]]>

Example:

<excerpt><![CDATA[Short object description]]></excerpt>

Supports multilingual format. In this case represents a list of tags with the language code (see p. 4) as the tag name and the object short description in this language as value. Object description should be wrapped in <![CDATA[ ]]>.

Example:

<excerpt>
   <ru><![CDATA[Краткое описание объекта]]></ru>
   <en><![CDATA[Short object description]]></en>
</excerpt>
 No

labels

The set of object labels specified as the list of label tags containing the label texts. Label text should be wrapped in <![CDATA[ ]]>

Example:

<labels>
   <label><![CDATA[Label 1]]></label>
   <label><![CDATA[Label 2]]></label>
</labels>

Supports multilingual format. In this case represents a list of tags with the language code (see p. 4) as the tag name and the list of label tags containing the label texts as value.

Example:

<labels>
   <ru>
      <label><![CDATA[Метка 1]]></label>
      <label><![CDATA[Метка 2]]></label>
   </ru>
   <en>
      <label><![CDATA[Label 1]]></label>
      <label><![CDATA[Label 2]]></label>
   </en>
</labels>
 No

deal

 Deal type numeric identifier. Catalog ID value, see p. 4 for deal types catalog. Yes

price

Object price as a number.

Attention: the minimum price for rental is 2000 euro per month and the minimum price for sale is 80000 euro; cheaper objects will not be imported.

 Yes

currency

 Currency in which the object price is specified. Three letter currency code. Available currencies are specified in the catalog, see p. 4 for currencies catalog. Yes

price_period

Specifies the period of the price in case of rental. One the two values:

  • monthly – in case of monthly price
  • daily – in case of daily price
 Yes, in case of rental

installment

Specifies availability of installment plan. Possible values:

  • 1 – yes
  • 0 – no
 No

type

 Object type numeric identifier. Catalog ID value, see p. 4, for object types catalog. Yes

region

Object region numeric identifier. Catalog ID value, see p. 4, for regions and districts catalog. Regions section.

Attention: cities preferred (city type in the catalog)

 Yes

district

Object district numeric identifier. Catalog ID value, see p. 4, for regions and districts catalog. Districts section.

Attention: if specified, the city value of the district from catalog should match the city specified in the region tag.

 No

status

 Object status numeric identifier. Catalog ID value, see p. 4, for statuses catalog. Yes

square

 Object general square in square meters as a number No

rooms

Object general rooms count as a number.

Attention:

  • Must contain the total number of rooms including living rooms. For example, for the 2+1 apartment the total number of rooms is 3 (2 bedrooms and 1 living room).
  • This tag is obligatory. If the property does not have rooms (e.g. land plot), please use the 0 value.
 Yes

bedrooms

 Object general bedrooms count as a number No

bathrooms

 Object general bathrooms count as a number No

floor

 Object floor as a number No

floors

 Total floors number. The building storeys number for an apartment, total object storeys for houses and villas. No

tosea

 Distance to the see in meters as a number. No

tocenter

 Distance to the city center in meters as a number. No

toairport

 Distance to the closest airport in kilometers as a number. No

finish

Construction completion date specified as the set of tags:

  • year – construction completion year in YYYY format
  • quarter – construction completion quarter as a number from 1 to 4

Example:

<finish>
   <year>2021</year>
   <quarter>1</quarter>
</finish>
 No

finished

Whether construction is completed. Possible values:

  • 1 – yes
  • 0 – no
 No

geo

Object latitude and longitude specified as the set of tags:

  • lat – latitude
  • lng – longitude

Example:

<geo>
   <lat>30.123456</lat>
   <lng>31.234567</lng>
</geo>
 No

developer

 Object developer numeric identifier. Catalog ID value, see p. 4, for developers catalog. No

images

Object photo gallery specified as a set of image tags, containing the photo URL.

Example:

<images>
   <image>http://domain.com/images/image1.jpg</image>
   <image>http://domain.com/images/image2.jpg</image>
   <image>http://domain.com/images/image3.jpg</image>
</images>

Attention:

  • The first image will be used as the main object photo and preview.
  • Only JPEG, GIF, PNG images are supported.
  • Images exceeding 5000 pixels in width or 4000 pixels in height will not be uploaded.
  • Maximum number of images for the object is 30. All images after 30 will be ignored.
  • Images should be available by the specified URL without any specific parameters (e.g. authorization, specific HTTP headers).
 No

agent

Your company employee marked as a manager for the object. Use the name tag containing the exact name of the employee specified in the Employees section of your private cabinet. If not specified, your company’s contact person will be specified as a seller on the turk.estate.

Example:

<agent>
   <name>John Smith</name>
</agent>
 No

features

The set of object features numeric identifiers specified as the list of feature tags. See p. 4 features catalog for the features identifiers values.

Example:

<features>
   <feature>5</feature>
   <feature>19</feature>
   <feature>71</feature>
</features>
 No

Attention:

  • For the multilingual fields the value’s language should match the language it is filled for. Values with the mismatching language will not be published.
  • Property translations to other languages should be passed as a single object using the multilingual format. Using different objects for each language version will cause the object’s dubbing on turk.estate.
  • To delete an object previously published via the XML-file, delete this object from the XML-file.

 

4. Catalogs

The list of language codes:

LanguageCode
Russian ru
English en
Turkish tr
German de
Finnish fi
Swedish sv
Norwegian no
Polish pl
Azerbaijani az
Kazakh kz
Belorussian by
Ukrainian ua

Catalogs list:

The list of catalogs is also available in your private cabinet on the website under Objects > Import > Documentation (https://turk.estate/en/agency-profile/properties/?autoload=documentation)

 

5. Fields usage examples

TagIncorrect usage exampleCorrect usage example

id

 
<object>
  <id>123</id>
  …
</object>
<object>
  <id>123</id>
  …
</object>
Using the same ID for the several objects is prohibited		 
<object>
  <id>123</id>
  …
</object>
<object>
  <id>1234</id>
  …
</object>
ID is unique for every object

edited

 
<edited>2020-01-17</edited>

<edited>January, 17th 2020</edited>

<edited>17/01/2020 05:33</edited>
Incorrect date formats		 
<edited>2020-01-17T08:05:33+0000</edited>
Date in ISO-8601 format

description

 
<description>
   Object description
</description>

Object description is not wrapped in <![CDATA[ ]]>

<description>
   <![CDATA[<p>Object description</p>]]>
</description>

Object description contains HTML tags

<description>
   <![CDATA[&lt;p&gt;Object description&lt;/p&gt;]]>
</description>

Object description contains HTML tags, though encoded

<description>
   <rus><![CDATA[Описание объекта]]></rus>
   <eng><![CDATA[Object description]]></eng>
</description>

Incorrect language codes in multilingual format

 
<description>
   <![CDATA[Описание объекта]]>
</description>

or

<description>
   <ru><![CDATA[Описание объекта]]></ru>
   <en><![CDATA[Object description]]></en>
</description>

excerpt

 
<excerpt>
   Short object description
</excerpt>

Short object description is not wrapped in <![CDATA[ ]]>

<excerpt>
   <![CDATA[<p> Short object description </p>]]>
</excerpt>

Short object description contains HTML tags

<excerpt>
   <![CDATA[&lt;p&gt; Short object description &lt;/p&gt;]]>
</excerpt>

Short object description contains HTML tags, though encoded

<excerpt>
   <rus><![CDATA[Краткое описание объекта]]></rus>
   <eng><![CDATA[Short object description]]></eng>
</excerpt>

Incorrect language codes in multilingual format

 
<excerpt>
   <![CDATA[Краткое описание объекта]]>
</excerpt>

or

<excerpt>
   <ru><![CDATA[Краткое описание объекта]]></ru>
   <en><![CDATA[Short object description]]></en>
</excerpt>

labels

 
<labels><![CDATA[Label 1]]> </labels>

Label is specified directly in the labels tag

<labels>
   <label>Label 1</label>
</labels>

Label text is not wrapped in <![CDATA[ ]]>

<labels>
   <label><![CDATA[<div>Label 1</div>]]></label>
</labels>

Label contains HTML tags

<labels>
   <label><![CDATA[&lt;div&gt;Label 1&lt;/div&gt;]]></label>
</labels>

Label contains HTML tags, though encoded

 
<labels>
   <label><![CDATA[Label 1]]></label>
   <label><![CDATA[Label 2]]></label>
</labels>

or

<labels>
   <ru>
      <label><![CDATA[Метка 1]]></label>
      <label><![CDATA[Метка 2]]></label>
   </ru>
   <en>
      <label><![CDATA[Label 1]]></label>
      <label><![CDATA[Label 2]]></label>
   </en>
</labels>

deal

 
<deal>sale</deal>

Numeric identifier from the catalog should be used for the deal type

<deal>10</deal>

Deal type ID does not exist in the catalog

 
<deal>1</deal>

price

 
<price>123 456</price>

Numeric values should not contain any spaces or delimiters

<price>1234,56</price>

Point should be used as a decimal delimiter

<price>123456 EUR</price>

Price should contain only numeric value

<deal>1</deal>
<price>123</price>
<price_period>monthly</price_period>

Rental price is less than 2000 euro per month

 
<price>123456</price>

currency

 
<currency>euro</currency>

<currency>$</currency>

<currency>€</currency>

Incorrect currency codes

 
<currency>EUR</currency>

price_period

 
<price_period> </price_period>

Rental period is not specified

<price_period>week</price_period>

Incorrect rental period

 
<price_period>monthly</price_period>

installment

 
<installment>yes</installment>

<installment>3</installment>
Incorrect tag values		 
<installment>1</installment>

type

 
<type>apartment</type>

Numeric identifier from the catalog should be used for the object type

<type>111</type>

Object type ID does not exist in the catalog

 
<type>1</type>

region

 
<region>Анталья</region>

<region>Antalya</region>

Numeric identifier from the catalog should be used for the object region

<region>123456</region>

Region ID does not exist in the catalog

 
<region>90</region>

district

 
<district>Tosmur</district>

Numeric identifier from the catalog should be used for the object district

<district>170</district>

Region ID is used instead of district ID

<region>170</region>
<district>1</district>

District does not match the region

 
<district>1</district>

status

 
<status>Secondary</status>

Numeric identifier from the catalog should be used for the object status

<status>10</status>

Status ID does not exist in the catalog

 
<status>1</status>

square

 
<square>150 m2</square>

Square should contain only the numeric value of the object’s square in square meters without units

<square>150-160</square>

A single value should be used for the object’s square

 
<square>150</square>

rooms

 
<rooms>studio</rooms>

<rooms>2+1</rooms>

Rooms count should be a numeric value

<rooms>2,3</rooms>

A single value should be used for the object’s rooms count

 
<rooms>2</rooms>

bedrooms

 
<bedrooms>2+1</bedrooms>

Bedrooms count should be a numeric value

<bedrooms>1,2</bedrooms>

A single value should be used for the object’s bedrooms count

 
<bedrooms>1</bedrooms>

bathrooms

 
<bathrooms >да</bathrooms >

Bathrooms count should be a numeric value

<bathrooms >1,2</bathrooms >

A single value should be used for the object’s bathrooms count

 
<bathrooms>2</bathrooms>

floor

 
<floor>five</floor>

Object’s floor should be a numeric value

<floor>5,6,7</floor>

A single value should be used for the object’s floor

 
<floor>5</floor>

floors

 
<floors>ten</floors>

Number of storeys should be a numeric value

<floors>10,12</floors>

A single value should be used for the number of storeys

 
<floors>10</floors>

tosea

 
<tosea>500 m</tosea>

Distance to the see should be a number in meters without units.

<tosea>0.5</tosea>

Distance to the sea should be in meters, not kilometers

 
<tosea>500</tosea>

tocenter

 
<tocenter>1000 m</tocenter>

Distance to the city center should be a number in meters without units.

<tocenter>1</tocenter>

Distance to the city center should be in meters, not kilometers

 
<tocenter>1000</tocenter>

toairport

 
<toairport>15 km</toairport>

Distance to an airport should be a number in kilometers without units.

<toairport>15000</toairport>

Distance to an airport should be in kilometers, not meters

 
<toairport>15</toairport>

finish

 
<finish>2021</finish>

Construction completion date is specified without year and quarter tags

<finish>
   <year>21</year>
   <quarter>1</quarter>
</finish>

A year should be in YYYY format

<finish>
   <year>2021</year>
   <quarter>II</quarter>
</finish>

Construction completion quarter should be an Arabic number

<finish>
   <year>2021</year>
</finish>

Construction completion quarter is not specified

 
<finish>
   <year>2021</year>
   <quarter>1</quarter>
</finish>

finished

 
<finished>yes</finished>

<finished>10</finished>

Incorrect tag values

 
<finished>0</finished>

geo

 
<geo>30.123456,31.234567</geo>

Coordinates are specified without lat and lng tags

<geo>
   <lat>36°49'13.4"N</lat>
   <lng>34°38'21.6"E</lng>
</geo>

Coordinates must be the decimal fractions

 
<geo>
   <lat>30.123456</lat>
   <lng>31.234567</lng>
</geo>

developer

 
<developer>Yekta Homes</developer>

Numeric identifier from the catalog should be used for the object developer

<developer>123456</developer>

Developer ID does not exist in the catalog

 
<developer>83</developer>

images

 
<images>http://domain.com/image1.jpg,
http://domain.com/image2.jpg,
http://domain.com/image3.jpg</images>

Images are specified without the image tags

<images>
   <image>/path/image1.jpg</image>
   <image>/path/image2.jpg</image>
   <image>/path/image3.jpg</image>
</images>

The images’ full URL should be specified

 
<images>
   <image>http://domain.com/image1.jpg</image>
   <image>http://domain.com/image2.jpg</image>
   <image>http://domain.com/image3.jpg</image>
</images>

agent

 
<agent>John Smith</agent>

An employee is specified with the name tag

<agent>
   <name>Nonexistent manager</name>
</agent>

The employee is not present in the employees list of your company on turk.estate

 
<agent>
   <name>John Smith</name>
</agent>

John Smith is present in the employees list of your company on turk.estate

features

 
<features>5,19,71</features>

Objects features are specified without the feature tags

<features>
   <feature>Близко к пляжу</feature>
   <feature>Близко к природе</feature>
   <feature>У моря</feature>
</features>

Numeric identifiers from the catalog should be used for the object features

 
<features>
   <feature>5</feature>
   <feature>19</feature>
   <feature>71</feature>
</features>

 

6. Frequently asked questions

How to delete an object previously added via the XML-file?

To delete an object previously added to turk.estate via the XML-file you need to delete this object from this XML-file. All absent objects are deleted during the data import from the file. Please mind that objects are identified be the id tag value.

 

We have update an object in our XML-file but the changes are not applied on turk.estate

This situation is possible for two reasons:

  1. The data import has not been started yet. Please note that the data imports are run only once a day.
  2. An object’s last edit time (the edited tag) has not changed. Each object’s last edit time, specified in the edited tag, is compared with the value specified in the previous import. An object data on the turk.estate is updated only if the last edit time is newer than the previous one.

 

An object image is present in the XML-file but the image is not displayed on turk.estate

Please check if the full image URL is specified in your XML-file and whether the image matches the requirements:

  • Image should be available by the specified URL without any specific parameters (e.g. authorization, specific HTTP headers).
  • Image should be in the JPEG, GIF or PNG format.
  • Image width should not exceed 5000 pixels, image height should not exceed 4000 pixels.
  • No more than 30 images is specified for the object. All images after 30 are ignored.

Please be informed that the object data and object images are not loaded simultaneously. First the object data is imported and only then the images are uploaded. In case of high load and a long image queue, image uploads may take up to several hours.

 

May I use HTML tags for the description markup? How can I format my objects’ description?

No, you cannot use any HTML tags for the object description. Please use the line breaks for markup.

 

What are the correct rooms and bedrooms values for the 2+1 property?

The rooms tag value should contain the total number of rooms including living rooms; the bedrooms tag value should contain the number of bedrooms. For the 2+1 property the total number of rooms is 3, so this value should be used for the rooms tag. 2+1 property has two bedrooms, so the correct value for the bedrooms tag is 2.

 

How can I check the import results?

The report on the last data import from your XML-file is available in your cabinet on the Properties > Import properties page. There you can see the last successful import date and the number of added, updated and removed objects. Click Show details link for the detailed report.

Share