Обновление данных через 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. Описание элементов
  7. Проверка файла

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

  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, address-add, working-time. Атрибут lang может принимать следующие значения:

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

Адрес

Укажите полный адрес одной строкой в элементе address, страну — в элементе country, название торгового центра, бизнес-центра, номер офиса, этаж — в элементе address-add.

<address lang="ru">город Киев, просп. Героев Сталинграда, 8а</address>
<country lang="ru">Украина</country>
<address-add lang="ru">ТЦ Ромашка, 2 этаж, офис 203</address-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>
        <address-add lang="ru">ТЦ Ромашка, 2 этаж, офис 203</address-add>
        <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>
        <inn>123456789123</inn> 
        <ogrn>9876543219876</ogrn>
        <actualization-date>1511724300</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>
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>
inn ИНН организации
<inn>123456789123</inn>
ogrn ОГРН организации
<ogrn>9876543219876</ogrn>
actualization-date

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

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

  • ДД.ММ.ГГГГ;
  • UNIX-time. Указывается в миллисекундах от 00:00:00.000 01.01.1970.
<actualization-date>13.11.2017</actualization-date>
<actualization-date>1511724300</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"/> 
feature-text-single Свойство филиала в текстовом формате.

Логин бесплатного Wi-Fi в отеле Якорь — «ssid»

<feature-text-single value="Yakor_free_wi-fi" name="ssid"/>

Проверка файла

На странице Валидатор XML-фидов сервиса Яндекс.Вебмастер вы можете проверить подготовленный файл.

Выберите схему валидации документа — Справочник и источник XML-данных для валидации — файл, ссылку или текст.

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