Обновление данных через XML-файл

Если в вашей сети более 30 филиалов, обновлять данные в Справочнике можно с помощью XML-файла.

Такое обновление имеет следующие преимущества :

  • Данные о ваших филиалах будут всегда актуальны во всех сервисах и мобильных приложениях Яндекса. Ваши потенциальные клиенты смогут легко добраться до ближайшего филиала с помощью Яндекс.Карт, Яндекс.Навигатора и других сервисов Яндекса.
  • Вы можете полностью автоматизировать передачу данных о филиалах, настроив выгрузку данных из своей базы 1С, ERP (SAP, Axapta) или других систем.
Внимание.

При передаче данных о сети необходимо:

  1. Предоставлять данные обо всех действующих филиалах.
  2. Поддерживать данные в актуальном состоянии.

Для настройки передачи данных:

  1. Подготовьте файл в формате XML.

  2. Выложите файл на свой сайт по обновляемой ссылке.

    Данные должны быть доступны по протоколу FTP, HTTP или HTTPS.

  3. Через форму передайте ссылку на файл для тестирования и подключения ежедневного обновления данных.

Подготовка файла и настройка делаются один раз. Все обновления происходят в автоматическом режиме.

Примечание.

Если вы планируете изменить URL, напишите об этом на partner@sprav.yandex.ua не менее чем за три рабочих дня до внесения изменений. Если вы не сделаете этого, данные о сети обновляться не будут.

Формат XML-файла

Передаваемые данные должны соответствовать спецификации формата XML.

  1. Общие требования
  2. Адрес
  3. Рубрика
  4. Дополнительные параметры
  5. Пример XML-файла
  6. Описание элементов

Общие требования

  1. XML-файл должен быть создан в кодировке UTF-8.
  2. Стандартный XML-заголовок должен начинаться с первой строки, с нулевого символа.

    Например:
    <?xml version="1.0" encoding="UTF-8"?>
  3. Корневой элемент должен иметь следующий вид:
    <companies></companies>
  4. Филиалы описываются с помощью элементов company, которые размещаются внутри корневого элемента. Количество элементов company может быть произвольным.
  5. Каждое свойство филиала следует обернуть в отдельный элемент. Подробнее см. в разделе Описание элементов.

    В данном примере выделен сайт:

    <url>http://antoshka.ua</url>
  6. Основные и дополнительные элементы должны быть расположены так же, как в примере и таблице с описанием элементов.
  7. Для каждого филиала обязательно должны быть указаны:
    • уникальный идентификатор — элемент company-id;
    • название — элемент name;
    • полный адрес местонахождения, с точностью до дома;
    • рубрика (вид деятельности);
    • сайт — элемент url;
    • дата актуализации XML-файла — элемент actualization-date;
    • координаты (для филиалов без точного адреса) — элемент coordinates.

    Чтобы пользователи могли уточнить информацию о вашей организации, укажите телефон в элементе phone.

    Примечание. Индекс передавать не нужно.
  8. Если для одного свойства есть несколько значений (например, телефонов), необходимо передавать несколько элементов с одинаковыми именами.
  9. В файле можно передавать только те элементы, которые указаны в подразделе Описание элементов.
  10. Некоторые элементы могут быть мультиязычными. К ним относятся элементы name, name-other, address, country, admn-area, sub-admn-area, locality-name, sub-locality-name, street, address-add, working-time. Атрибут lang может принимать следующие значения:

    • ru — русский язык;
    • ua — украинский язык;
    • by — белорусский язык;
    • kz — казахский язык.
  11. Чтобы информация о сети организаций была полной, передавайте максимальный набор элементов для каждого филиала сети (в том числе дополнительные элементы).
  12. Каждый филиал должен быть представлен в отдельной карточке: для каждого филиала должен быть указан свой идентификатор с отдельным набором элементов.
  13. В данных не должно быть HTML-элементов. В стандарте XML недопустимы символы с ASCII-кодами в диапазоне значений от 0 до 31 в текстовых полях. Исключением являются значения 9, 10, 13 — табуляция, перевод строки, возврат каретки. Также этот стандарт строго требует заменять в тексте некоторые символы: & на &amp;.

Адрес

Вы можете передать адрес несколькими способами:

Указать полный адрес в элементе address

Полный адрес указывается одной строкой в элементе address. Страна — в элементе country:

<address lang="ru">город Киев, просп. Героев Сталинграда, 8а</address>
<country lang="ru">Украина</country>
Указать адрес в элементах address и locality-name

Улица и номер дома указывается в элементе address, населенный пункт — в элементе locality-name, область, край или республика — в элементе admn-area. Страна указывается отдельно в элементе country:

<country lang="ru">Украина</country>
<admn-area lang="ru">Киевская область</admn-area>
<locality-name lang="ru">город Киев</locality-name>
<address lang="ru">просп. Героев Сталинграда, 8а</address>
Разбить адрес на отдельные элементы

Адрес разбивается на составные элементы — admn-area, sub-admn-area, locality-name, street, house, house-add, corps, build, possession, km, address-add. Элемент address при этом не используется. Страна указывается отдельно в элементе country:

<country lang="ru">Украина</country>
<admn-area lang="ru">Киевская область</admn-area>
<locality-name lang="ru">город Киев</locality-name>
<street lang="ru">просп. Героев Сталинграда</street>
<house>8</house>
<house-add>а</house-add>

Рубрика

Чтобы указать рубрику, используйте идентификаторы рубрик Справочника.

Дополнительные параметры

Через XML-файл вы можете передавать дополнительные параметры для вашей сети или филиала — например, указать, есть ли возле вашего торгового центра парковка или в какой валюте можно получить деньги в вашем банкомате.

Эта информация передается с помощью дополнительных элементов. Чтобы получить XML-файл со списком возможных элементов для вашей рубрики, напишите на partner@sprav.yandex.ua.

Пример XML-файла

<?xml version="1.0" encoding="UTF-8"?> 
<companies>
    <company>
        <company-id>770704034</company-id>
        <name lang="ru">Антошка</name>
        <address lang="ru">город Киев, просп. Героев Сталинграда, 8а</address>
        <country lang="ru">Украина</country>
        <phone>
            <number>+380 (44) 581-61-17</number>
            <ext>555</ext>
            <info>секретарь</info>
            <type>phone</type>
        </phone>
        <phone>
            <ext/><type>phone</type>
            <number>+ 0 (800) 30-60-63</number>
            <info/>
        </phone>
        <email>info@antoshka.ua</email>
        <url>http://www.antoshka.com.ua</url>
        <add-url>http://www.antoshka-add.ua</add-url>
        <info-page>http://www.test.ua/antoshka</info-page>
        <working-time lang="ru">ежедн. 10:00-21:00</working-time>
        <rubric-id>184107252</rubric-id>
        <rubric-id>184107260</rubric-id>
        <actualization-date>1305705951000</actualization-date>
        <photos gallery-url="http://test.ua/antoshka/gallery">
            <photo url="http://test.ua/antoshka/11_b.jpg" alt="Первый зал" type="interior"/>
            <photo url="http://test.ua/antoshka/19_b.jpg" type="exterior"/>
            <photo url="http://test.ua/antoshka/25_b.jpg"/>
        </photos>
        <feature-numeric-multiple name="license_number" value= "004555"/>
        <feature-in-units-single name="minimum_order"  unit="money"  unit-value="grn"  value="300"/>
    </company>
</companies>

Описание элементов

Наименование Описание Пример
company-id Уникальный идентификатор филиала (присваивается владельцем сети). Может содержать цифры и латинские буквы.
<company-id>770704034</company-id> 
name Название филиала. Указывается без кавычек, с учетом регистра. Мультиязычный элемент.
<name lang="ru">Антошка</name>
name-other Альтернативное название филиала (если названий несколько, то каждое указывается в отдельном элементе). Мультиязычный элемент.
<name-other lang="ru">ИП Иванов</name-other>
address Адрес филиала (одной строкой). Мультиязычный элемент.
Примечание. Если элемент содержит только название улицы и номер дома, необходимо использовать элемент locality-name с указанием населенного пункта.
<address lang="ru">город Киев, просп. Героев Сталинграда, 8а</address>  
<address lang="ru">просп. Героев Сталинграда, 8а</address><locality-name lang="ru">город Киев</locality-name>
country Страна. Указывается полностью, без сокращений. Мультиязычный элемент.
<country lang="ru">Украина</country>
admn-area Название области, края, республики. Мультиязычный элемент.
<admn-area lang="ru">Киевская область</admn-area>
sub-admn-area Район в составе области. Слово «район» указывается полностью, без сокращений. Мультиязычный элемент.
<sub-admn-area lang="ru">Киево-Святошинский район</sub-admn-area>
locality-name Тип (город, село, поселок, деревня и т. п.) и название населенного пункта. Указывается полностью, без сокращений. Мультиязычный элемент.
<locality-name lang="ru">город Киев</locality-name>
sub-locality-name Название дополнительного населенного пункта города или района в черте крупного города (село Шевченко, село Троещина, Соломенский район). Тип населенного пункта указывается полностью, без сокращений. Мультиязычный элемент.
<locality-name lang="ru">город Киев</locality-name><sub-locality-name lang="ru">село Шевченко</sub-locality-name>
street Тип (улица, переулок, набережная, шоссе, проезд, бульвар, площадь, аллея, проспект, тупик, проезд, шоссе, дорога, трасса) и название улицы. Указывается полностью, без сокращений. Мультиязычный элемент.
<street lang="ru">проспект Победы</street> 
house Номер дома. Указывается цифрами, без специальных символов и букв.
<house>101</house>
house-add

Дополнение к номеру дома. Указывается цифрами или буквами, без пояснительных слов и сокращений.

<house>11</house><house-add>а</house-add>
<house>11</house><house-add>3</house-add>
corps Номер корпуса. Указывается цифрами или буквами, без пояснительных слов и сокращений.
<corps>5А</corps>
build Номер строения. Указывается цифрами и (или) буквами, без пояснительных слов и сокращений.
<build>Б</build>
possession Номер владения. Указывается цифрами и (или) буквами, без пояснительных слов и сокращений.
<possession>6В</possession>
km Километр трассы. Указывается цифрами, без пояснительных слов и сокращений.
<km>175</km>
address-add Дополнительная информация к адресу, которая не относится к другим элементам. Мультиязычный элемент.
<address-add lang="ru">БЦ Regus, офис 547</address-add>
coordinates Составной элемент. Координаты по широте и долготе.
<coordinates><lon>34.427524546763365</lon> <lat>53.219950313883814</lat></coordinates> 
lon Координата по долготе. В качестве разделителя целой и дробной части используется точка.
<lon>34.427524546763365</lon> 
lat Координата по широте. В качестве разделителя целой и дробной части используется точка.
<lat>53.219950313883814</lat>
phone Составной элемент. Номер телефона (если номеров несколько, то каждый указывается в отдельном элементе).
<phone><number>+380 (44) 581-61-17</number><ext>555</ext> <type>phone</type><info>секретарь</info></phone>
number Номер стационарного или мобильного телефона. Указывается в формате: [код страны] ([код города]) [номер телефона].
<number>+380 (44) 581-61-17</number>
ext Добавочный номер, без пояснений, слов и разделителей.
<ext>555</ext>
info Информация о номере, например: директор, секретарь.
Примечание. В этом элементе не должно быть информации о типе телефона.
<info>секретарь</info>
type Тип телефона. Принимает одно из трех значений:
  • phone — телефон;
  • fax — факс;
  • phone-fax — телефон-факс.
<type>phone</type>
email Адрес электронной почты (если адресов несколько, то каждый указывается в отдельном элементе).
<email>info@antoshka.ua</email>
url Основной сайт сети. Указывается в нижнем регистре, полностью, включая http:// или https://.
<url>http://www.antoshka.ua</url>
add-url Дополнительный сайт сети (например, ссылки на страницы в социальных сетях).
Примечание. Адрес страницы с информацией о сети на сайте партнера указывается в элементе info-page.
<add-url>http://www.antoshka-add.ua</add-url>
info-page Адрес страницы с информацией о сети на сайте партнера Справочника. Указывается в нижнем регистре, полностью, включая http:// или https://.
Примечание. Адрес должен содержать доменное имя сайта партнера.
<info-page>http://www.test.ua/antoshka</info-page>
working-time Часы работы. Выходные, нерабочие дни не указываются. Мультиязычный элемент.
<working-time lang="ru">ежедн. 10:00-21:00</working-time>
rubric-id Идентификатор рубрики, к которой относится данный филиал (если рубрик несколько, то каждая указывается в отдельном элементе).
Примечание. У каждого филиала может быть до трех рубрик, но хотя бы одна из них должна совпадать с рубрикой сети.
<rubric-id>184106414</rubric-id>
<rubric-id>184106394</rubric-id>
actualization-date

Дата актуализации. Соответствует времени последней актуализации данных. Используется для того, чтобы не скачивалась информация, полученная при предыдущей проверке.

Содержимое может быть указано в формате:

  • ДД.ММ.ГГГГ;
  • UNIX-time. Указывается в миллисекундах от 00:00:00.000 01.01.1970.
<actualization-date>13.05.2013</actualization-date>
<actualization-date>1305705951000</actualization-date>
photos

Ссылка на галерею или страницу на сайте сети со всеми фотографиями. Если фотографий несколько, то каждая указывается в отдельном элементе photo.

Элемент photo может содержать следующие атрибуты:

  • alt — текстовое описание фотографии в свободной форме;
  • type — тип фотографии:
    • exterior — экстерьер;
    • interior — интерьер;
    • food — блюда, напитки.
<photos gallery-url="http://test.ua/antoshka/gallery">
<photo url="http://test.ua/antoshka/11_b.jpg" alt="Первый зал" type="interior"/>
</photos>
Дополнительные элементы
feature-boolean Свойство филиала. Может иметь два значения: 1 («да») или 0 («нет»). Если свойств несколько, каждое указывается в отдельном элементе.

В филиале есть сеть Wi-Fi:

<feature-boolean name="wi_fi"   value="1"/> 
feature-enum-single Свойство филиала.

Вид театра — театр абсурда:

<feature-enum-single name="theater_type" value="absurdist_theatre"/>
feature-enum-multiple Свойство филиала. Если свойств несколько, каждое указывается в отдельном элементе.

Тип тура — автобусный тур:

<feature-enum-multiple name="tour_type" value="bus_tour"/>
feature-numeric-single Свойство филиала с числовым значением.

В филиале находится три телевизора:

<feature-numeric-single name="number_of_screen"  value="3"/> 
feature-numeric-multiple Свойство филиала с числовым значением. Если свойств несколько, каждое указывается в отдельном элементе.

Номер лицензии:

<feature-numeric-multiple name="license_number" value= "004555"/>
feature-in-units-single Свойство филиала, значение которого определено в единицах измерения.

Минимальная сумма доставки составляет 150 гривен:

<feature-in-units-single name="minimum_order"  unit="money"  unit-value="grn"  value="150"/> 
feature-in-units-multiple Свойство филиала, значение которого определено в единицах измерения. Если свойств несколько, каждое указывается в отдельном элементе.

В гостинице 200 одноместных номеров:

<feature-in-units-multiple name="ats_by_type"  unit="apartment_type"  unit-value="single" value="200"/>
feature-range-single Свойство филиала, имеющее диапазонное значение.

В филиале есть банкетный зал на 15–20 мест:

<feature-range-single name="number_seats_banquet_hall" from="15"  to="20"/> 
feature-range-multiple Свойство филиала, имеющее диапазонное значение. Если свойств несколько, каждое указывается в отдельном элементе.

Стоимость билетов — от 40 до 60 гривен:

<feature-range-multiple name="tickets"  unit="money" unit-value="grn" from="40" to="60"/>
feature-range-in-units-single Свойство филиала, имеющее диапазонное значение в единицах измерения.

Стоимость одной минуты составляет 3–6 гривен:

<feature-range-in-units-single name="price_1_min"  unit="money" unit-value="grn" from="3" to="6"/> 
feature-range-in-units-multiple Свойство филиала, имеющее диапазонное значение в единицах измерения. Если свойств несколько, каждое указывается в отдельном элементе.

Стоимость женской стрижки с укладкой — от 400 до 1000 гривен:

<feature-range-in-units-multiple name="women_haircut" unit="money" unit-value="grn" from="400" to="1000"/>