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

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

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

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

Подготовка файла

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

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

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

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

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

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

Загрузка файла в интерфейсе

  1. На странице сети перейдите в раздел Филиалы. В блоке Управление филиалами выберите Файл.

  2. Укажите ссылку на подготовленный файл, выберите тип «xml» и нажмите Проверить. Проверка файла может занять несколько часов.

  3. Если проверка файла прошла успешно, нажмите кнопку Результаты проверки. В открывшемся окне проверьте изменения в филиалах. На карте может быть показано до 50 филиалов с изменениями. Нажмите Все верно, начать загрузку в базу. Данные из файла пройдут модерацию и будут загружены в базу Справочника. При большом объеме данных загрузка может занять несколько суток.

    Если в результате проверки файла будут обнаружены ошибки, вы увидите сообщение об этом. Исправьте ошибки и снова отправьте файл на проверку.

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

На Яндекс.Картах новые филиалы и другие изменения будут доступны через несколько дней.

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

Формат 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://www.yakor-anapa.ru</url>
  6. Основные и дополнительные элементы должны быть расположены так же, как в примере и таблице с описанием элементов.
  7. Для каждого филиала обязательно должны быть указаны:
    • уникальный неизменный идентификатор — элемент company-id;
    • название — элемент name;
    • полный адрес местонахождения, с точностью до дома;
    • время работы — элемент working-time;
    • сайт — элемент 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">город Екатеринбург, просп. Ленина, 101, а</address>
<country lang="ru">Россия</country>
<address-add lang="ru">ТЦ Ромашка, 2 этаж, офис 203</address-add>

Рубрика

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

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

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

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

  1. На странице сети перейдите на вкладку Филиалы.
  2. В блоке Управление филиалами выберите Файл.
  3. Нажмите Выгрузить признаки.

Если есть вопросы по выгрузке файла с дополнительными параметрами, напишите на partner@sprav.yandex.ru.

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

<?xml version="1.0" encoding="UTF-8"?> 
<companies>
    <company>
        <company-id>770704034</company-id>
        <name lang="ru">Якорь</name>
        <shortname lang="ru">Якорь</shortname>
        <address lang="ru">город Екатеринбург, просп. Ленина, 101, а</address>
        <country lang="ru">Россия</country>
        <address-add lang="ru">ТЦ Ромашка, 2 этаж, офис 203</address-add>
        <phone>
            <number>+7 (343) 375-13-99</number>
            <ext>555</ext>
            <info>секретарь</info>
            <type>phone</type>
        </phone>
        <phone>
            <ext/><type>phone</type>
            <number>+7 (800) 200-23-45</number>
            <info/>
        </phone>
        <email>info@yakor-anapa.ru</email>
        <url>http://www.yakor-anapa.ru</url>
        <add-url>http://www.yakoranapa.ru</add-url>
        <info-page>http://www.test.ru/yakor-anapa</info-page>
        <working-time lang="ru">ежедн. 10:00-21:00</working-time>
        <rubric-id>184106414</rubric-id>
        <rubric-id>184106394</rubric-id>
        <inn>123456789123</inn> 
        <ogrn>9876543219876</ogrn>
        <actualization-date>1511724300</actualization-date>
        <photos gallery-url="http://test.ru/yakor-anapa/gallery">
            <photo url="http://test.ru/yakor-anapa/11_b.jpg" alt="Ресторан отеля" type="interior"/>
            <photo url="http://test.ru/yakor-anapa/19_b.jpg" type="exterior"/>
            <photo url="http://test.ru/yakor-anapa/25_b.jpg"/>
            <photo url="http://test.ru/yakor-anapa/26_b.jpg"/>
            <photo url="http://test.ru/yakor-anapa/17_b.jpg"/>
            <photo url="http://test.ru/yakor-anapa/drink1.jpg" alt="Коктейль в баре отеля" type="food"/>
        </photos>
        <feature-boolean name="internet" value="1"/>
        <feature-enum-single name="star" value="five"/>
        <feature-numeric-single name="room_number" value="15"/>
        <feature-enum-multiple name="hotel_type" value="art_hotel"/>
        <feature-text-single value="Yakor_free_wi-fi" name="ssid"/>
    </company>
    <company>
        <company-id>7707040070</company-id>
        <name lang="ru">Якорьбанк</name>
        <shortname lang="ru">Якорьбанк</shortname>
        <name-other lang="ru">Якорьбанк, платёжное устройство</name-other>
        <address lang="ru">Россия, Республика Татарстан, Зеленодольский район, село Нурлаты, улица Гагарина, 46</address>
        <phone>
            <ext/><type>phone</type>
            <number>+7 (800) 999-99-90</number>
            <info/>
        </phone>
        <url>http://www.yakorbank.ru/</url>
        <working-time lang="ru">будни 8:30-18:00, сб 9:00-14:30</working-time>
        <rubric-id>184106974</rubric-id>
        <actualization-date>23.09.2019</actualization-date>
        <coordinates>
          <lon>48.295532</lon>
          <lat>55.616051</lat>
        </coordinates>
    </company>
</companies>

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

Наименование Описание Пример
company-id Уникальный неизменный идентификатор филиала (присваивается владельцем сети). Может содержать произвольный набор цифр и латинских букв.
<company-id>770704034</company-id> 
name Название филиала. Указывается без кавычек, с учетом регистра. Мультиязычный элемент.
<name lang="ru">Якорь</name>
shortname Короткое название филиала для отображения около меток на картах, до 25 символов. Указывается без кавычек, с учетом регистра. Мультиязычный элемент.
<shortname lang="ru">Якорь</shortname>
name-other Альтернативное название филиала (если названий несколько, то каждое указывается в отдельном элементе). Мультиязычный элемент.
<name-other lang="ru">ИП Иванов</name-other>
address Адрес филиала (одной строкой). Мультиязычный элемент.
Примечание. Если элемент содержит только название улицы и номер дома, необходимо использовать элемент locality-name с указанием населенного пункта.
<address lang="ru">город Екатеринбург, 
проспект Ленина, 101а</address>
<address lang="ru">проспект Ленина, 101а</address>
 <locality-name lang="ru">город Екатеринбург</locality-name>
country Страна. Указывается полностью, без сокращений. Мультиязычный элемент.
<country lang="ru">Россия</country>
address-add Дополнительная информация к адресу, которая не относится к другим элементам. Мультиязычный элемент.
<address-add lang="ru">БЦ Бенуа, этаж 5, офис 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>8 (800) 200-23-45</number>
   <ext>555</ext> <type>phone</type>
   <info>секретарь</info>
</phone>
number Номер стационарного или мобильного телефона. Указывается в формате: [код страны] ([код города]) [номер телефона].
<number>8 (800) 200-23-45</number>
<number>+7 (3456) 23-45-67</number>
ext Добавочный номер, без пояснений, слов и разделителей.
<ext>555</ext>
info Информация о номере, например: директор, секретарь.
Примечание. В этом элементе не должно быть информации о типе телефона.
<info>секретарь</info>
type Тип телефона. Принимает одно из трех значений:
  • phone — телефон;
  • fax — факс;
  • phone-fax — телефон-факс.
<type>phone</type>
email Адрес электронной почты (если адресов несколько, то каждый указывается в отдельном элементе).
<email>info@yakor-anapa.ru</email>
url Основной сайт сети. Указывается в нижнем регистре, полностью, включая http:// или https://.
<url>http://www.yakor-anapa.ru</url>
add-url Дополнительный сайт сети (например, ссылки на страницы в социальных сетях).
Примечание. Адрес страницы с информацией о филиале на сайте сети указывается в элементе info-page.
<add-url>http://www.fb.com/anchor-hotel</add-url>
info-page Адрес страницы с информацией о филиале на сайте сети. Указывается в нижнем регистре, полностью, включая http:// или https://.
Примечание. Адрес должен содержать доменное имя сайта сети.
<info-page>http://www.yakor-anapa.ru/branch1/photos</info-page>
working-time Часы работы. Выходные, нерабочие дни не указываются. Мультиязычный элемент.
<working-time>ежедн. 10:00-21:00</working-time>
<working-time>пн-пт 9:00-19:00, 
сб-вс 10:00-18:00</working-time>

С обедом:

<working-time>пн-пт: 10:00-19:00, обед 13:00-14:00; 
сб: 10:30-16:00, обед 13:00-13:30</working-time>

С перерывом:

<working-time>пн-пт: 08:00-17:00, 
перерыв: 12:00-13:00</working-time>

Круглосуточно:

<working-time>круглосуточно</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.ru/yakor-anapa/gallery">
<photo url="http://test.ru/yakor-anapa/11_b.jpg" 
 alt="Ресторан отеля" type="interior"/>
</photos>
<photos gallery-url="http://test.ru/yakor-anapa/gallery">
<photo url="http://test.ru/yakor-anapa/drink1.jpg" 
alt="Коктейль в баре отеля" type="food"/>
</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 Свойство филиала, значение которого определено в единицах измерения.

Минимальная сумма доставки составляет 300 рублей:

<feature-in-units-single name="minimum_order"  
unit="money"  unit-value="rub"  value="300"/> 
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 Свойство филиала, имеющее диапазонное значение. Если свойств несколько, каждое указывается в отдельном элементе.

Стоимость билетов — от 100 до 150 рублей:

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

Стоимость одной минуты составляет 7–10 рублей:

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

Стоимость женской стрижки с укладкой — от 1000 до 3000 рублей.

<feature-range-in-units-multiple name="women_haircut" 
unit="money" unit-value="rub" from="1000" to="3000"/> 
feature-text-single Свойство филиала в текстовом формате.

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

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