Довідник

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

Якщо у вашій мережі понад 30 філій, оновлювати дані в Довіднику можна за допомогою XML-файлу.

Це оновлення має такі переваги:

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

Увага! 

У разі передавання даних про мережі необхідно:

  1. Надавати дані про всі активні філії.
  2. Підтримувати дані в актуальному стані.

Для налаштування передавання даних:

  1. Підготуйте файл у форматі XML.

  2. Викладіть файл на свій сайт за оновлюваним посиланням.

    Дані повинні бути доступні за протоколами FTP, HTTP або HTTPS.

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

Підготовка файлу та налаштування робляться один раз. Усі оновлення відбуваються в автоматичному режимі.

Примітка. 

Якщо ви плануєте змінити URL, напишіть про це на partner@sprav.yandex.ua не менше ніж за три робочі дні до внесення змін. Якщо ви не зробите цього, дані про мережу не оновлюватимуться.

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

Передавані дані повинні відповідати специфікації формату XML.

Загальні вимоги

  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="uk">місто Київ, просп. Героїв Сталінграда, 8А</address>
<country lang="uk">Україна</country>
Зазначити адресу в елементах address і locality-name

Вулиця і номер будинку зазначаються в елементі address, населений пункт — в елементі locality-name, область, край або республіка — в елементі admn-area. Країна зазначається окремо в елементі country:

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

Адреса розбивається на складові елементи — admn-area, sub-admn-area, locality-name, street, house, house-add, corps, build, possession, km, address-add. Елемент address при цьому не використовується. Країна зазначається окремо в елементі country:

<country lang="uk">Україна</country>
<admn-area lang="uk">Київська область</admn-area>
<locality-name lang="uk">місто Київ</locality-name>
<street lang="uk">просп. Героїв Сталінграда</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
[no-highlight[

Унікальний ідентифікатор філії (присвоюється власником мережі). Може містити цифри і латинські літери.

]no-highlight]
>770704034</company-id> <name
[no-highlight[

Назва філії. Зазначається без лапок, з урахуванням регістру. Мультимовний елемент.

]no-highlight]
lang="uk">Антошка</name> <address
[no-highlight[

Адреса філії (одним рядком). Мультимовний елемент.

Примітка. Якщо елемент містить лише назву вулиці та номер будинку, необхідно використовувати елемент locality-name із зазначенням населеного пункту.

]no-highlight]
lang="uk">місто Київ, просп. Героїв Сталінграда, 8а</address> <country
[no-highlight[

Країна. Зазначається повністю, без скорочень. Мультимовний елемент.

]no-highlight]
lang="uk">Україна</country> <phone
[no-highlight[

Складовий елемент. Номер телефону (якщо номерів кілька, то кожен зазначається в окремому елементі).

]no-highlight]
> <number
[no-highlight[

Номер стаціонарного або мобільного телефону. Зазначається у форматі: [код країни] ([код міста]) [номер телефону].

]no-highlight]
>+380 (44) 581-61-17</number> <ext
[no-highlight[

Додатковий номер, без пояснень, слів і роздільників.

]no-highlight]
>555</ext> <info
[no-highlight[

Інформація про номер, наприклад директор, секретар.

Примітка. У цьому елементі не повинно бути інформації про тип телефона.

]no-highlight]
>секретар</info> <type
[no-highlight[

Тип телефона. Приймає одне із трьох значень:

  • phone — телефон;
  • fax — факс;
  • phone-fax — телефон-факс.

]no-highlight]
>phone</type> </phone> <phone
[no-highlight[

Складовий елемент. Номер телефону (якщо номерів кілька, то кожен зазначається в окремому елементі).

]no-highlight]
> <ext
[no-highlight[

Додатковий номер, без пояснень, слів і роздільників.

]no-highlight]
/><type
[no-highlight[

Тип телефона. Приймає одне із трьох значень:

  • phone — телефон;
  • fax — факс;
  • phone-fax — телефон-факс.

]no-highlight]
>phone</type> <number
[no-highlight[

Номер стаціонарного або мобільного телефону. Зазначається у форматі: [код країни] ([код міста]) [номер телефону].

]no-highlight]
>+ 0 (800) 30-60-63</number> <info
[no-highlight[

Інформація про номер, наприклад директор, секретар.

Примітка. У цьому елементі не повинно бути інформації про тип телефона.

]no-highlight]
/> </phone> <email>info@antoshka.ua</email> <url
[no-highlight[

Основний сайт мережі. Зазначається у нижньому регістрі, повністю, включаючи http:// або https://.

]no-highlight]
>http://www.antoshka.com.ua</url> <add-url
[no-highlight[

Додатковий сайт мережі (наприклад, посилання на сторінки в соціальних мережах).

Примітка. Адреса сторінки з інформацією про мережу на сайті партнера зазначається в елементі info-page.

]no-highlight]
>http://www.antoshka-add.ua</add-url> <info-page
[no-highlight[

Адреса сторінки з інформацією про мережу на сайті партнера Довідника. Зазначається у нижньому регістрі, повністю, включаючи http:// або https://.

Примітка. Адреса повинна містити доменне ім‘я сайту партнера.

]no-highlight]
>http://www.test.ua/antoshka</info-page> <working-time
[no-highlight[

Режим роботи. Вихідні, неробочі дні не зазначаються. Мультимовний елемент.

]no-highlight]
lang="uk">щоденно 10:00-21:00</working-time> <rubric-id
[no-highlight[

Ідентифікатор рубрики, до якої належить ця філія (якщо рубрик кілька, то кожна зазначається в окремому елементі).

Примітка. У кожної філії може бути до трьох рубрик, але хоча б одна із них повинна збігатися з рубрикою мережі.

]no-highlight]
>184107252</rubric-id> <rubric-id
[no-highlight[

Ідентифікатор рубрики, до якої належить ця філія (якщо рубрик кілька, то кожна зазначається в окремому елементі).

Примітка. У кожної філії може бути до трьох рубрик, але хоча б одна із них повинна збігатися з рубрикою мережі.

]no-highlight]
>184107260</rubric-id> <actualization-date
[no-highlight[

Дата актуалізації. Відповідає часу останньої актуалізації даних. Використовується для того, щоб не завантажувалась інформація, отримана під час попередньої перевірки.

Вміст може бути зазначено у форматі:

  • ДД.ММ.РРРР;
  • UNIX-time. Зазначається в мілісекундах від 00:00:00.000 01.01.1970.
]no-highlight]
>1305705951000</actualization-date> <photos
[no-highlight[

Посилання на галерею або сторінку на сайті мережі з усіма фотографіями. Якщо фотографій кілька, кожна зазначається в окремому елементі photo.

Елемент photo може містити такі атрибути:

  • alt — текстовий опис фотографії в довільній формі;
  • type — тип фотографії: exterior — екстер‘єр, interior — інтер‘єр.
]no-highlight]
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
[no-highlight[

Властивість філії з числовим значенням. Якщо властивостей кілька, кожна зазначається в окремому елементі.

]no-highlight]
name="license_number" value= "004555"/> <feature-in-units-single
[no-highlight[

Властивість філії, значення якої визначено в одиницях вимірювання.

]no-highlight]
name="minimum_order" unit="money" unit-value="grn" value="300"/> </company> </companies>

Опис елементів

НайменуванняОписПриклад
company-id Унікальний ідентифікатор філії (присвоюється власником мережі). Може містити цифри і латинські літери.
<company-id>770704034</company-id> 
name Назва філії. Зазначається без лапок, з урахуванням регістру. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<name lang="uk">Антошка</name>
name-other Альтернативна назва філії (якщо назв кілька, то кожна зазначається в окремому елементі). Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<name-other lang="uk">ІП Іванов</name-other>
address Адреса філії (одним рядком). Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
Примітка. Якщо елемент містить лише назву вулиці та номер будинку, необхідно використовувати елемент locality-name із зазначенням населеного пункту.
<address lang="uk">місто Київ, просп. Героїв Сталінграда, 8а</address>  
<address lang="uk">просп. Героїв Сталінграда, 8а</address><locality-name lang="uk">місто Київ</locality-name>
country Країна. Зазначається повністю, без скорочень. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<country lang="uk">Україна</country>
admn-area Назва області, республіки. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<admn-area lang="uk">Київська область</admn-area>
sub-admn-area Район у складі області. Слово «район» зазначається повністю, без скорочень. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<sub-admn-area lang="uk">Києво-Святошинський район</sub-admn-area>
locality-name Тип (місто, село, селище тощо) та назва населеного пункту. Зазначається повністю, без скорочень. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<locality-name lang="uk">місто Київ</locality-name>
sub-locality-name Назва додаткового населеного пункту міста або району в межах великого міста (село Шевченка, селище Троєщина, Солом'янський район). Тип населеного пункту зазначається повністю, без скорочень. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<locality-name lang="uk">місто Київ</locality-name><sub-locality-name lang="uk">село Шевченка</sub-locality-name>
street Тип (вулиця, провулок, набережна, шосе, проїзд, бульвар, площа, алея, проспект, тупик, проїзд, шосе, дорога, траса) і назва вулиці. Зазначається повністю, без скорочень. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<street lang="uk">проспект Перемоги</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 Додаткова інформація про адресу, що не належить до інших елементів. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<address-add lang="uk">БЦ 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>
e-mail Адреса електронної пошти (якщо адрес кілька, то кожна зазначається в окремому елементі).
<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 Режим роботи. Вихідні, неробочі дні не зазначаються. Мультимовний елемент
[no-highlight[

Деякі елементи можуть бути мультимовними. До них належать елементи 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 — казахська мова.
]no-highlight]
.
<working-time lang="uk">щоденно 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 — інтер'єр.
<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"/> 
Передати файл