Требования к передаче данных

Чтобы ваши объявления попали в базу сервиса, подготовьте фид с данными согласно требованиям.

Формат передачи данных

Фид с объявлениями составляется на XML (Extensible Markup Language). XML не позволяет использовать первые 32 ASCII-символа в текстовых полях (исключения — табуляция, перевод строки, возврат каретки). Также стандарт строго требует кодировать в тексте следующие символы:

Символ, который нужно заменить Код для XML-файла
" "
& &
> >
< &lt;
' &apos;
Кодировка

Кодировка файла — UTF-8.

Заголовок документа

XML-документ должен начинаться со стандартного XML-заголовка с нулевого символа первой строки.

<?xml version="1.0" encoding="utf-8"?>
Корневой элемент

Корневой элемент XML-фида (realty-feed) должен содержать элемент generation-date с датой создания фида (дата генерации фида, т.е. указывается дата последней генерации фида) и элементы offer, в каждом из которых должна находиться информация из одного объявления. Чтобы указать пространство имен в XML, используйте атрибут xmlns="http://webmaster.yandex.ru/schemas/feed/realty/2010-06".

<realty-feed xmlns="http://webmaster.yandex.ru/schemas/feed/realty/2010-06">
<generation-date>2010-10-05T16:36:00+04:00</generation-date>
 <offer>
  ...
 </offer>
 ...
</realty-feed>

Весь контент располагать внутри тега. Аттрибуты не указанные в этом руководстве будут игнорироваться при обработке фида.

Формат даты

Все даты и время следует указывать согласно стандарту ISO 8601. В общем случае — в формате YYYY-MM-DDTHH:mm:ss+00:00, где:

  • YYYY — год;

  • MM — месяц;

  • DD — день;

  • HH — час;

  • mm — минута;

  • ss — секунда;

  • +00:00 — указание часового пояса (для Алматы — +06:00).

Требования к объявлениям в фиде

  • Фид с объявлениями необходимо разместить на своем домене и предоставить в виде URL-ссылки.
  • Структура фида должна соответствовать формату XML.
  • Фид должен содержать только валидные объявления. Валидным считается объявление, для которого все поля фида заполнены согласно формату XML.
  • В фиде надо передавать только те параметры, которые указаны в объявлении.

    Если в объявлении есть несколько значений одного параметра (например, несколько фотографий), используйте несколько одинаковых тегов.

  • Каждое объявление должно быть посвящено одному объекту недвижимости.
  • В каждом объявлении, размещенном агентством недвижимости, должно присутствовать явное указание на агентство.
  • Чтобы добавить новую информацию в объявление, необходимо обновить существующее объявление, но не удалять и не дублировать его. Обновленное объявление должно иметь тот же internal-id.
  • В текстах объявлений и в описании характеристик объектов не должно быть HTML-кода.
  • Фид должен содержать актуальные объявления. Актуальным считается объявление, содержащее достоверную информацию о реальном объекте, который можно купить или арендовать.

    Объявление считается неактуальным, если объект уже продан, сдан в аренду, по указанному телефонному номеру невозможно дозвониться, цена в объявлении существенно отличается от запрашиваемой, не совпадает адрес или другие параметры.

Общая информация об объявлении

У элемента offer есть обязательный атрибут internal-id, который должен быть уникальным для каждого объявления. internal-id может состоять из цифр, латинских и кириллических букв, знаков. Мы рекомендуем заполнять его номером из вашей базы данных.

<offer internal-id="А1245">
 ...
</offer>
Внимание. Элементы со строго ограниченным набором значений могут содержать только перечисленные варианты. Использование других значений приведет к ошибке обработки фида.

Рубрика

Элемент Обязательность Описание
type

Тип сделки.

Строго ограниченные значения:

  • «продажа»
  • «аренда»
category

Категория объекта.

Строго ограниченные значения:

  • «квартира»
  • «комната»
  • «дом»
  • «здание»
  • «база»
  • «склад»
  • «офисное помещение»
  • «торговое помещение»
  • «бизнес»
  • «участок»
  • «дача»
  • «гараж»

Расположение объекта

Поля передаются внутри <location>

Элемент Обязательность Описание
country

Страна

Строго ограниченные значения:

  • «Казахстан»
district

Область

Область Казахстана, не нужно указывать для Нур-Султан, Алматы, Шымкент список областей

locality-name

Название населенного пункта, город

sub-locality-name

Район в населенном пункте. Используется у locality-name «Алматы», «Нур-Султан», «Караганда»

Строго ограниченные значения для «Алматы»:

  • «Алатауский»
  • «Алмалинский»
  • «Ауэзовский»
  • «Бостандыкский»
  • «Жетысуский»
  • «Илийский»
  • «Карасайский»
  • «Медеуский»
  • «Наурызбайский»
  • «Талгарский»
  • «Турксибский»

Строго ограниченные значения для «Нур-Султан»:

  • «Алматы»
  • «Есиль»
  • «Сарыарка»
  • «Косшы»
  • «Байконур»
  • «Прочее»

Строго ограниченные значения для «Караганда»:

  • «Город»
  • «Юго-Восток»
  • «Майкудук»
  • «Михайловка»
  • «Пришахтинск»
  • «р-н ЖБИ»
  • «р-н Нового рынка»
  • «Сортировка»
  • «Федоровка»
  • «Прочее»
address-street

Название улицы

address-number

Номер дома

intersection

На пересечении с улицей

latitude

Географическая широта.

Можно узнать её на Яндекс.Картах, сразу под адресом.

longitude

Географическая долгота.

Можно узнать её на Яндекс.Картах, сразу под адресом.

Пример
<location>
      <country>Казахстан</country>
      <district>Карагандинская область</district>
      <locality-name>Караганда</locality-name>
      <sub-locality-name>Майкудук</sub-locality-name>
      <address-street>Абая</address-street>
      <address-number>7/2</address-number>
      <intersection>Гоголя</intersection>
      <latitude>49.818938</latitude>
      <longitude>73.094720</longitude>
</location>

Информация о продавце или арендодателе

Поля передаются внутри <sales-agent>

Элемент Обязательность Описание
email

email пользователя на kn.kz

тут передаются email субриэлтора, или email автора фида
phone

Номер телефона, указывается в международном формате.(+77011234567)

Если номеров несколько, каждый из них необходимо передавать в отдельном элементе phone.

Пример
<sales-agent>
      <email>example@kn.kz</email>
      <phone>+77011234567</phone>
      <phone>+77051234567</phone>
</sales-agent>

Информация об условиях сделки

Поля передаются внутри <price>

Элемент Обязательность Описание
value

Цена в национальной валюте Казахстана

period

Период аренды. Используется в type «аренда».

Строго ограниченные значения:

  • «день»
  • «месяц»
Примеры

для продажи

<price>
      <value>100500</value>
</price>

для аренды

<price>
      <value>100500</value>
      <period>день</period>
</price>

Общая площадь.

Поля передаются внутри <area>

Элемент Обязательность Описание
value

Площадь. Указывается числовое значение.

unit

Единица площади помещения или участка.

Строго ограниченные значения:

  • «кв. м»
  • «сотка»
  • «гектар»
Если не указан, то считается как «кв. м»
Пример
<area>
      <value>102</value>
      <unit>кв. м</unit>
</area>

Жилая площадь.

Поля передаются внутри <living-space>

Элемент Обязательность Описание
value

Площадь. Указывается числовое значение.

unit

Единица площади.

Строго ограниченные значения:

  • «кв. м»
  • «сотка»
  • «гектар»
Если не указан, то считается как «кв. м»
Пример
<living-space>
      <value>102</value>
      <unit>кв. м</unit>
</living-space>

Площадь кухни.

Поля передаются внутри <kitchen-space>

Элемент Обязательность Описание
value

Площадь.

Может быть число, либо слово «студия»
Пример
<kitchen-space>
      <value>102</value>
</kitchen-space>
или
<kitchen-space>
      <value>студия</value>
</kitchen-space>

Площадь участка.

Поля передаются внутри <lot-area>

Элемент Обязательность Описание
value

Площадь. Указывается числовое значение.

unit

Единица площади.

Строго ограниченные значения:

  • «кв. м»
  • «сотка»
  • «гектар»
Если не указан, то считается как «кв. м»
Пример
<lot-area>
      <value>102</value>
      <unit>кв. м</unit>
</lot-area>

Описание жилого помещения (Описание объекта)

Элемент Обязательность Описание
rooms

Общее количество комнат.

floor

Этаж

description

Описание объекта. Информационный текст без html.

mortgage

Находится ли недвижимость в залоге?

Строго ограниченные значения:

  • «Да»
  • «Нет»
image

Фотография.

Публичный URL фотографий объекта. Можно указывать несколько тегов.

nomination-house

Наименование дома. Используется в category «дом».

Строго ограниченные значения:

  • «Жилой дом»
  • «Коттедж»
  • «Таунхаус»
  • «Особняк»
  • «Дом на 2 хозяина»
  • «Дом барачного типа»
  • «Времянка»
nomination-build

Наименование здания. Используется в category «здание».

Строго ограниченные значения:

  • «Здание»
  • «Бизнес-центр»
  • «Производственное здание»
  • «Административное здание»
nomination-storage

Наименование базы или склада. Используется в category «база», «склад».

Строго ограниченные значения:

  • «База производственно-складская»
  • «База промышленная»
  • «База производственная»
  • «Складское помещение»
nomination-stead

Наименование земельного участка. Используется в category «участок».

Строго ограниченные значения:

  • «гараж»
  • «ИЖС»
  • «коммерческое»
  • «крестьянское хозяйство»
  • «личное подсобное хозяйство»
  • «МЖС»
  • «многофункциональное»
  • «производственное»
  • «пром. база»
  • «садоводство»
  • «сельское хозяйство»
  • «склад»
nomination

Наименование.

Строка. Используется в category «действующий бизнес», «офисное помещение», «торговое помещение»

Описание здания.

Элемент Обязательность Описание
floors-total

Общее количество этажей в доме.

building-name

Название жилого комплекса.

kn-building-id

Идентификатор жилого комплекса в базе KNа.

Нужен чтобы объявления соответствовали правильному ЖК.

Примечание. Используется только в некоторых городах.

Список жилых комплексов.

building-type

Тип дома. (Материал стен)

Строго ограниченные значения для общих домов:

  • «деревянный»
  • «кирпичный»
  • «панельный»
  • «монолитный»
  • «блочный»

Строго ограниченные значения для частных домов:

  • «кирпичный»
  • «панельный»
  • «монолитный»
  • «деревянный»
  • «каркасно-камышитовый»
  • «пеноблочный»
  • «сэндвич-панели»
  • «каркасно-щитовой»
  • «шлакоблочный»
  • «иное»
built-year

Год сдачи (год постройки)

Год по григорианскому календарю в формате YYYY
ceiling-height

Высота потолков в метрах.

Другие поля.

Элемент Обязательность Описание
readiness

Готовность. Используется в category «дом»

Строго ограниченные значения:

  • «40% готовности»
  • «50% готовности»
  • «60% готовности»
  • «70% готовности»
  • «80% готовности»
  • «90% готовности»
garage

Наличие гаража. Используется в category «дом»

Строго ограниченные значения:

  • «нет»
  • «есть»
  • «на 2 машины»
  • «на 3 машины»
  • «2 гаража»
state

Состояние. Используется в category «дом», «здание», «офисное помещение», «торговое помещение»

Строго ограниченные значения для «дом»:

  • «без ремонта»
  • «с ремонтом»
  • «с евроремонтом»

Строго ограниченные значения для «здание»:

  • «без ремонта»
  • «евроремонт»
  • «капитальный ремонт»
  • «косметический ремонт»
  • «недостроенное»
  • «ремонт»
  • «черновая отделка»
  • «чистовая отделка»

Строго ограниченные значения для «офисное помещение», «торговое помещение»:

  • «без ремонта»
  • «евроремонт»
  • «капитальный ремонт»
  • «косметический ремонт»
  • «ремонт»
  • «черновая отделка»
  • «чистовая отделка»
watersupply

Водоснабжение. Используется в category «дом», «дача»

Строго ограниченные значения для «дом»:

  • «центральное водоснабжение»
  • «скважина»
  • «колодец»
  • «другое»

Строго ограниченные значения для «дача»:

  • «центральное»
  • «скважина»
  • «летний водопровод»
  • «можно подключить»
sewerage

Канализация. Используется в category «дом», «дача»

Строго ограниченные значения для «дом»:

  • «центральная канализация»
  • «септик»
  • «другое»

Строго ограниченные значения для «дача»:

  • «центральная»
  • «септик»
  • «можно подключить»
toilet

Санузел. Используется в category «дом»

Строго ограниченные значения:

  • «санузел раздельный»
  • «санузел совмещенный»
  • «2 санузла и более»
  • «санузел во дворе»
  • «санузел в доме»
heating

Отопление. Используется в category «дом»

Строго ограниченные значения:

  • «без отопления»
  • «комбинированное отопление»
  • «отопление на газе»
  • «отопление на жидком топливе»
  • «отопление на твердом топливе»
  • «паровое отопление»
  • «электрическое отопление»
  • «центральное отопление»
  • «другое»
internet

Интернет. Используется в category «дом», в type «аренда» category «квартира»

Строго ограниченные значения:

  • «без интернета»
  • «Wi-Fi»
  • «проводной интернет»
furniture

Мебель. Используется в category «дом», в type «аренда» category «квартира»

Строго ограниченные значения:

  • «без мебели»
  • «частично меблирован»
  • «полностью меблирован»
tupik

Наличие ж/д тупика. Используется в category «база», «склад»

Строго ограниченные значения:

  • «без ж/д тупика»
  • «с ж/д тупиком»
location-premises

Находится. Используется в category «офисное помещение», «торговое помещение»

Строго ограниченные значения:

  • «в административном здании»
  • «в бизнес-центре»
  • «в жилом доме»
  • «в промышленном здании»
  • «в торговом центре»
  • «прочее»