Здесь описывается первая версия XML формата файлов, служащих для обмена информацией о сделках с объектами недвижимости.
В данном репозитории находятся:
Описываемый формат называется "REX" (real estate exchange). Синоним - "наш формат".
Импорт - это преобразование из чужого формата в наш.
Экспорт - преобразование из нашего формата в чужой.
Продажа - это когда клиент продаёт свой объект через нас.
Покупка - когда клиент хочет что-то купить через нас (фактически, это задача по поиску недвижимости по заданным критериям).
Аренда - когда клиент хочет что-то арендовать через нас.
Сдача в аренду - когда клиент хочет сдать свой объект через нас в аренду.
Рекламное издание - журнал, сайт, газета или другой ресурс, который публикует (обычно за деньги) информацию об объектах недвижимости. Принимает данные в структурированном виде.
Рекламный источник - то же, что и издание. С нашей точки зрения - это место, откуда можно взять информацию об объектах недвижимости в каком-то структурированном виде.
Реклама - это отправка агентством недвижимости данных о своих объектах в то или иное издание. Соответственно, реклама касается, в первую очередь, сделок по продаже и сдаче в аренду.
Импорт из источника - это получение откуда-нибудь структурированной информации об объектах недвижимости и сохранение в базе данных нашего проекта с целью дальнейшего анализа.
Если не указано иное, то всегда: расстояние - в километрах, периоды времени - в месяцах, площадь - в квадратных метрах, денежные суммы - в рублях, физические размеры объектов - в метрах, размеры файлов и данных - в байтах.
Отдельно следует заметить, что площади земельных участков - тоже в квадратных метрах (для единообразия). В большинстве источников эти площади указываются в сотках или гектарах. Сотка - это 100 квадратных метров. Гектар - это 10000 квадратных метров. Эти площади при экспорте и импорте нужно будет умножать или делить.
Корневой элемент - root, единственный его обязательный атрибут - rev, определяющий версию формата. Данные о сделках хранятся в коллекции orders, каждая сделка описывается одним элементом order. Атрибуты: id - номер сделки в нашем проекте, ctm - unix timestamp времени создания сделки, mtm - unix timestamp времени последнего изменения сделки. Все атрибуты необязательны.
В элемент order вложены элементы, описывающие сделку. Эти элементы могут идти в произвольном порядке; практически все могут отсутствовать. Единственное исключение - элемент type, определяющий отношения компании и клиента (продажа, покупка, аренда, сопровождение, etc). Без этих отношений сделки не может быть, поэтому данный элемент обязателен. Значение - одно из словаря order_type.
Ниже приведён общий вид XML файла в формате REX. Он технически некорректен (корректный пример - в отдельном файле), зато в нём приведены краткие комментарии по поводу каждого элемента, присутствующего в order.
<root rev="1">
<orders>
<order id="13234" ctm="1281381923" mtm="12391820398">
<title>Название сделки</title>
<type>Тип сделки: продажа, аренда, покупка, etc</type>
<group>Данные о группе объектов</group>
<price>
Цена продажи, аренды, etc. Зависит от типа сделки. Для аренды указывается срок, для которого указана стоимость аренды
</price>
<rent>Дополнительные параметры, относящиеся к аренде</rent>
<owner>
Владелец объекта: ФИО, контактная информация, группа и компания (если владелец - агент и принадлежит к какой-то компании). Если объект рекламируется частным лицом - тут информация о нём.
</owner>
<comment>Комментарий к сделке в произвольной текстовой форме</comment>
<mortgage>Данные об ипотеке, субсидиях</mortgage>
<estate>Параметры объекта недвижимости</estate>
<meta>Метаинформация: когда и откуда импортирован, сопутствующие файлы, etc</meta>
</order>
<order>...</order>
<order>...</order>
...
</orders>
</root>Элементы внутри order могут содержать текст, числа, логические значения и словарные значения. Общее правило: если тег отсутствует (а отсутствовать могут практически все теги), значение не известно или не определено. Если тег присутствует, то его значение определено и должно быть валидным.
Если элемент содержит произвольный текст (как title или comment > text), то этот текст заключается внутрь
<![CDATA[...]]>Ограничений на длину текста нет нигде.
Если элемент содержит число, то и хорошо. Это может быть целое или вещественное число. Однако есть нюанс. Вообще говоря, order может описывать не один объект недвижимости, а сразу диапазон похожих объектов. Это редкая ситуация, которая при импорте и экспорте вряд ли будет встречаться. Тем не менее, у каждого элемента, который должен содержать числовое значения есть необязательный атрибут max, который содержит верхнюю границу значения для описываемого диапазона. Число, заключённое внутри тега, описывает, соответственно, нижнюю границу. Например,
<price><full max="2000000">1500000</full></price>описывает цену от полутора до двух миллионов.
Если элемент содержит логическое значение, то оно записывается как true или false. Означает наличие или отсутствие какого-то признака.
Если элемент содержит словарное значение, то у него должен присутствовать числовой атрибут id, указывающий на id записи в соответствующем словаре. Значение, заключённое внутри тега, описывает строковое представление этой записи. Каждый конкретный элемент, который должен содержать словарное значение, связан с конкретным словарём. В примере у таких элементов присутствует необязательный атрибут dic, в котором указано название словаря. В реальных файлах этот атрибут может и должен быть опущен. Пример:
<type dic="order_type" id="2">покупка</type>Здесь значение "покупка" имеет id=2 в словаре order_type.
При импорте данных может сложиться такая ситуация, что в словаре внешнего источника есть какое-то значение, которое отсутствует в нашем словаре. Например, в чужом формате встречается тип сделки "субаренда", которого нет у нас. Такие конфликты случаются достаточно часто. В подобной ситуации, если невозможно провести какого-то однозначного соответствия между значениями и нельзя расширить наш собственный словарь, можно использовать элемент без указания атрибута id. Таким образом, информация при импорте не потеряется, просто будет храниться в немного менее структурированном виде. Пример:
<type>субаренда</type>.Обязательных полей с точки зрения схемы валидации крайне немного, так как формат призван быть гибким. Однако и при импорте, и при экспорте нужно стараться указать как можно больше значений во имя богатства описания. Обязательные поля следующие:
Надо отметить, что только элемент type является безусловно обязательным. Скажем, тип объекта недвижимости нужно указывать, только если есть тег estate.
Ниже приведены списки строковых и словарных полей. Они более или менее актуальны, однако первичный источник информации - файл с примером.
Строковые поля:
Словарные поля (в скобках указано название словаря)
Дальше приведена информация по конкретным тегам элемента order и значениям, которые они могут содержать.
Тип сделки. Словарь order_type. Единственный обязательный тег. В случае необходимости для уточнения типа сделки (например, указания, что продажа не "свободная", а "встречная") используется тег mortgage > term (дополнительные условия сделки).
Цена. Имеет вложенные теги full (полная стоимость), per_meter (стоимость за метр квадратный), utility_fees (размер ежемесячных коммунальных платежей в рублях) и commission (комиссия агента и клиента). Все цены всегда в рублях, если не указан атрибут currency у вложенных тегов full и per_meter. Комиссия - в процентах, если не указана, то клиентская - 100%, агентская - 50%. Если тип сделки - продажа, то цены - это цены продажи. Если тип - сдача в аренду, то цены - цены аренды. Цена аренды указывается за месяц, если значение тега rent > short - false (долгосрочная аренда) и за день, если значение тега rent > short - true (краткосрочная аренда).
Если не указан атрибут currency, то цена считается указанной в рублях. Если указан - то в той валюте, в которой указано. Пока что разрешены следующие валюты: RUR (рубли), EUR (евро), USD (доллары США). В будущем, возможно, добавятся другие.
Цена может быть как выражена конкретным значением, так и считаться договорной. Для этого предназначен атрибут negotiable (по умолчанию false). Для совместимости со старыми версиями также считается, что цена договорная, если в теге price нет атрибута negotiable и нет вложенных тегов full и per_meter. Этот вариант считается устаревшим и поддерживается только при импорте.
Если в теге price есть атрибут negotiable и есть один или оба вложенных тега full и/или per_meter, то это означает конкретную цену и то, что возможен торг.
Группировка объектов, позволяющая вкладывать объекты друг в друга. Например, можно описать жилой комплекс, состоящий из множества квартир. Обязательный вложенный тег - type, задающий тип группы объектов (словарь group_type). Необязательный вложенный тег - members - члены группы. Членами группы должны быть полноценные элементы order (которые, в свою очередь, могут группировать другие элементы, если это необходимо).
Арендная специфика. Вложенный тег term указывает минимальный срок, на который может сдаваться объект, имеется также необязательный атрибут max (максимально возможный срок сдачи объекта в аренду). Единица измерения - месяц. Вложенный тег pledge содержит логическое значение, которое истинно тогда, когда за объект необходимо вносить залог. Вложенный тег pledge_term может принимать одно из словарных значений для описания размера залога (0,5 месяца, 1 месяц, 1,% месяца и т.д.). Логический вложенный тег short указывает на то, что аренда - краткосрочная (посуточная). Вложенные теги tenants и neighbors описывают количество съёмщиков и соседей.
Описывается персона (и опционально - компания и подразделение внутри компании), которая ответственна за сделку. Если речь идёт об объекте на экспорт, то тут хранится информация об агенте, который занимается сделкой. В случае импорта тут может быть информация о частнике-владельце или об агентствах-конкурентах.
Вложенный тег agent описывает физ.лицо (агента или частника). У этого тега может быть атрибут id, указывающий на словарь employee. В тег вложены теги name, phone и email, определяющие, соответственно, ФИО, телефон и email человека. Если телефонов или адресов электронной почты несколько, то в тегах phone и email указываются основные. Дополнительные перечисляются в тегах phone и email, вложенных в тег additional (owner > agent > additional). Атрибут id этих тегов (как основных, так и вложенных в additional) указывает на словарь contact_ownership и позволяет определить, является ли контакт домашним, рабочим, мобильным и т.д.
Вложенные словарные теги company и group обозначают, какой компании и какому подразделению внутри компании принадлежит объект. Тег url позволяет указать URL сайта компании.
При импорте может быть ситуация, когда известна только компания и телефон. В этом случае, название компании указывается в теге company (желательно найти перед этим компанию в словаре), телефон - в теге agent > phone.
Необязательный текстовый комментарий к сделке. Хранится во вложенном обязательном теге text. Есть дополнительные вложенные теги html и short для, соответственно, HTML-версии и краткого описания.
Всё, что относится к ипотеке. Если тег имеется, значит, ипотека возможна. Если тег отсутствует, ипотека невозможна. Необязательные вложенные теги:
Данные, относящиеся к банковской ячейке. Необязательный вложенный тег bank - словарное значение, определяющее банк, в котором арендована ячейка. Необязательный вложенный тег date определяет дату выемки денег из ячейки.
Описание объекта недвижимости. Очень большой, но необязательный тег. Для импорта и экспорта - основной.
Метаинформация об объекте.
Для импортированных объектов указывается источник (source), дата и время импорта (imported}, URL источника данных (url), URL конкретного объекта на сайте-источнике (link), ID объекта в источнике (extid), степень выделенности объекта в издании (highlight), любые дополнительные структурированные данные (extra). Все теги необязательны.
Значение в теге highlight - это число, которое равно 0, если объявление не выделено, и больше нуля, если объявление выделено. Чем больше это число, тем выделеннее объявление. Каждое издание позволяет выделять объявления по-своему, некоторые не позволяют вообще. Как именно преобразовывается выделение в число (и обратно) - остаётся на совести конвертера. Пример для БН: 0 - обычная строка, 1 - жирная строка, 2 - золотая строка. Пример для БКН: 0 - обычная строка, 1 - жирная строка. Пример для старого формата ИРР: 0 - обычное объявление, 1 - треугольник. Пример для ГдеЭтогоДома: 0 - обычное объявление, 1 - выделить рамкой (is_border=true), 2 - выделить цветом (is_premium=true).
Кроме того, с объектом могут идти какие-то связанные файлы, например, фотографии, планировки, видеообзоры, etc. Для этого служит коллекция attachments, каждый элемент attachment которой описывает отдельный файл.