YML формат — Yandex Market Language

YML (Yandex Market Language) — стандартный формат XML-файла для передачи данных о товарах в сервис promosearch.ru. Основан на спецификации Яндекс.Маркета.

Важные моменты:

• При большом количестве товаров (более 500 000) рекомендуется создавать несколько фидов для оптимизации загрузки
• Поиск использует только данные из YML-фида — вся информация должна быть актуальной и корректной
• Если файл генерируется динамически и процесс занимает много времени — настройте выгрузку по крону в статический файл для быстрого доступа

Если у вас есть вопросы по формированию YML-фида — обратитесь в техническую поддержку: https://promosearch.ru/#contact

1. Общая структура файла

YML-файл представляет собой XML-документ с определённой структурой элементов.

Минимальная структура:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE yml_catalog SYSTEM "shops.dtd">
<yml_catalog date="2024-01-15 12:00">
  <shop>
    <name>Название магазина</name>
    <company>Название компании</company>
    <url>https://myshop.ru</url>
    <currencies>
      <currency id="RUB" rate="1"/>
    </currencies>
    <categories>
      <category id="1">Электроника</category>
    </categories>
    <offers>
      <offer id="12345" available="true">
        <!-- Поля товара -->
      </offer>
    </offers>
  </shop>
</yml_catalog>

Требования к файлу:

• Кодировка: UTF-8 (обязательно)
• Размер: не более 2 ГБ
• Формат: валидный XML
• Расширение файла: .xml или .yml

2. Элемент yml_catalog

Корневой элемент документа.

Атрибут:

Пример:

<yml_catalog date="2024-01-15 14:30">
  ...
</yml_catalog>

3. Раздел shop

Содержит всю информацию о магазине и товарах.

Обязательные элементы раздела shop:

• <name>, <company>, <url> — основная информация о магазине
• <currencies> — описание валют
• <categories> — дерево категорий товаров
• <offers> — список товаров

Необязательные элементы:

• <stickers> — визуальные метки для товаров
• <platform>, <version>, <agency>, <email> — дополнительная информация

Общие сведения о магазине

Пример:

<shop>
  <name>Мой магазин</name>
  <company>ООО "Интернет-торговля"</company>
  <url>https://myshop.ru</url>
  <platform>MODX</platform>
  <version>3.0</version>
  <email>info@myshop.ru</email>
  ...
</shop>

Валюты

Раздел <currencies> описывает валюты, используемые в магазине.

Структура:

<currencies>
  <currency id="RUB" rate="1"/>
  <currency id="USD" rate="CBRF"/>
  <currency id="EUR" rate="90.5"/>
</currencies>

Атрибуты элемента currency:

Одна из валют должна быть базовой (rate="1"). Обычно это RUB.

Категории

Раздел <categories> содержит дерево категорий товаров.

Структура:

<categories>
  <category id="1">Электроника</category>
  <category id="2" parentId="1">Смартфоны</category>
  <category id="3" parentId="1">Ноутбуки</category>
  <category id="4">Одежда</category>
</categories>

Атрибуты элемента category:

Правила:

• id должен быть уникальным в пределах файла
• Название категории — текст между тегами <category> и </category>
• Максимальная вложенность — без ограничений
• Если parentId не указан — категория корневая

Стикеры

Раздел <stickers> описывает визуальные метки (бейджи), которые можно назначить товарам.

Структура:

<stickers>
  <sticker id="0">
    <text>Хит продаж</text>
    <bg>#f5b942</bg>
    <color>#ffffff</color>
  </sticker>
  <sticker id="1">
    <text>Новинка</text>
    <bg>#2cc739</bg>
    <color>#ffffff</color>
  </sticker>
  <sticker id="2">
    <text>Только сегодня</text>
    <bg>#d40000</bg>
    <color>#ffffff</color>
  </sticker>
  <sticker id="3">
    <text>Пример стикера</text>
    <bg>#4154f1</bg>
    <color>#ffffff</color>
  </sticker>
</stickers>

Поля элемента sticker:

Правила:

• Раздел <stickers> размещается между <categories> и <offers>
• id должен быть уникальным в пределах файла
• Стикеры назначаются товарам через поле <stickers> в описании товара (см. раздел 4)

Товары

Раздел <offers> содержит список всех товаров.

<offers>
  <offer id="12345" available="true">
    <!-- Описание товара -->
  </offer>
  <offer id="12346" available="false">
    <!-- Описание товара -->
  </offer>
</offers>

4. Описание товара (offer)

Каждый товар описывается элементом <offer>.

Атрибуты offer:

Обязательные поля

Эти поля обязательны для каждого товара.

Пример минимального товара:

<offer id="12345" available="true">
  <name>Смартфон Samsung Galaxy S23</name>
  <url>https://myshop.ru/product/12345</url>
  <price>59990</price>
  <currencyId>RUB</currencyId>
  <categoryId>2</categoryId>
</offer>

Необязательные поля

Эти поля добавляют дополнительную информацию о товаре.

Группировка вариантов товара (group_id)

Поле group_id используется для объединения различных вариантов одного товара (разные цвета, размеры, комплектации). Все товары с одинаковым group_id считаются вариантами одной модели и могут отображаться вместе в результатах поиска.

Пример — разные цвета одного смартфона:

<!-- Чёрный вариант -->
<offer id="12345" available="true" group_id="galaxy-s23-128">
  <name>Смартфон Samsung Galaxy S23 128GB Black</name>
  <url>https://myshop.ru/product/12345</url>
  <price>59990</price>
  <currencyId>RUB</currencyId>
  <categoryId>2</categoryId>
  <group_id>galaxy-s23-128</group_id>
  <param name="Цвет">Черный</param>
  <param name="Память">128 ГБ</param>
</offer>

<!-- Белый вариант -->
<offer id="12346" available="true" group_id="galaxy-s23-128">
  <name>Смартфон Samsung Galaxy S23 128GB White</name>
  <url>https://myshop.ru/product/12346</url>
  <price>59990</price>
  <currencyId>RUB</currencyId>
  <categoryId>2</categoryId>
  <group_id>galaxy-s23-128</group_id>
  <param name="Цвет">Белый</param>
  <param name="Память">128 ГБ</param>
</offer>

<!-- Зелёный вариант -->
<offer id="12347" available="true" group_id="galaxy-s23-128">
  <name>Смартфон Samsung Galaxy S23 128GB Green</name>
  <url>https://myshop.ru/product/12347</url>
  <price>61990</price>
  <currencyId>RUB</currencyId>
  <categoryId>2</categoryId>
  <group_id>galaxy-s23-128</group_id>
  <param name="Цвет">Зеленый</param>
  <param name="Память">128 ГБ</param>
</offer>

Правила использования:

• group_id указывается и как атрибут элемента <offer>, и как отдельный элемент внутри товара
• Значение group_id должно быть одинаковым для всех вариантов одной модели
• Рекомендуется использовать осмысленные идентификаторы (например: galaxy-s23-128, iphone-15-pro-256)
• Товары без group_id считаются уникальными, не имеющими вариантов

Параметры товара (param)

Элемент <param> используется для описания характеристик товара, на основе которых строятся фасетные фильтры в поиске.

Структура:

<param name="Объём">5</param>
<param name="Цвет">двухцветный</param>
<param name="Материал">алюминий</param>
<param unit="мм" name="Толщина стенки">8</param>
<param unit="см" name="Высота">34</param>
<param unit="см" name="Диаметр">17</param>
<param unit="кг" name="Вес">3</param>
<param name="Страна">Афганистан</param>

Атрибуты элемента param:

Правила:

• Значение параметра указывается между тегами <param> и </param>
• Можно указать любое количество параметров
• Параметры с одинаковым name группируются в один фасетный фильтр
• Для числовых параметров рекомендуется указывать unit

Пример товара с дополнительными полями:

<offer id="12345" available="true" group_id="galaxy-s23-128">
  <name>Смартфон Samsung Galaxy S23 128GB Black</name>
  <url>https://myshop.ru/product/12345</url>
  <price>59990</price>
  <currencyId>RUB</currencyId>
  <categoryId>2</categoryId>
  <group_id>galaxy-s23-128</group_id>
  <picture>https://myshop.ru/images/12345-1.jpg</picture>
  <picture>https://myshop.ru/images/12345-2.jpg</picture>
  <picture>https://myshop.ru/images/12345-3.jpg</picture>
  <stickers>0,1</stickers>
  <description>Флагманский смартфон Samsung Galaxy S23 с экраном 6.1", процессором Snapdragon 8 Gen 2 и камерой 50 МП.</description>
  <vendor>Samsung</vendor>
  <vendorCode>SM-S911BZKDEUC</vendorCode>
  <model>Galaxy S23</model>
  <oldprice>69990</oldprice>
  <count>15</count>
  <rating>4.8</rating>
  <priority>150</priority>
  <min_quantity>1</min_quantity>
  <multiplicity>1</multiplicity>
  <keyword>самсунг галакси смартфон телефон android</keyword>
  <location>Москва, склад №1</location>
  <barcode>8806094732345</barcode>
  <param name="Цвет">Черный</param>
  <param name="Память">128 ГБ</param>
  <param unit="дюйм" name="Диагональ экрана">6.1</param>
  <param name="Операционная система">Android</param>
  <param unit="МП" name="Камера">50</param>
  <param unit="г" name="Вес">168</param>
  <regionData>
    <region id="604">
      <url>https://msk.myshop.ru/product/12345</url>
      <price>59990</price>
      <oldprice>69990</oldprice>
      <available>true</available>
      <count>15</count>
      <desc>Флагманский смартфон Samsung Galaxy S23. Доставка по Москве за 1 день</desc>
      <weight>10</weight>
      <stickers>0,1</stickers>
    </region>
    <region id="699">
      <url>https://spb.myshop.ru/product/12345</url>
      <price>58990</price>
      <oldprice>68990</oldprice>
      <available>true</available>
      <count>8</count>
      <weight>5</weight>
      <stickers>1</stickers>
    </region>
  </regionData>
</offer>

5. Полный пример YML-файла

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE yml_catalog SYSTEM "shops.dtd">
<yml_catalog date="2024-01-15 14:30">
  <shop>
    <name>Мой магазин</name>
    <company>ООО "Интернет-торговля"</company>
    <url>https://myshop.ru</url>
    <platform>MODX</platform>
    <email>info@myshop.ru</email>

    <currencies>
      <currency id="RUB" rate="1"/>
      <currency id="USD" rate="CBRF"/>
    </currencies>

    <categories>
      <category id="1">Электроника</category>
      <category id="2" parentId="1">Смартфоны</category>
      <category id="3" parentId="1">Ноутбуки</category>
    </categories>

    <stickers>
      <sticker id="0">
        <text>Хит продаж</text>
        <bg>#f5b942</bg>
        <color>#ffffff</color>
      </sticker>
      <sticker id="1">
        <text>Новинка</text>
        <bg>#2cc739</bg>
        <color>#ffffff</color>
      </sticker>
      <sticker id="2">
        <text>Только сегодня</text>
        <bg>#d40000</bg>
        <color>#ffffff</color>
      </sticker>
    </stickers>

    <offers>
      <!-- Товар с полным набором полей -->
      <offer id="12345" available="true" group_id="galaxy-s23-128">
        <name>Смартфон Samsung Galaxy S23 128GB Black</name>
        <url>https://myshop.ru/product/12345</url>
        <price>59990</price>
        <currencyId>RUB</currencyId>
        <categoryId>2</categoryId>
        <group_id>galaxy-s23-128</group_id>
        <picture>https://myshop.ru/images/12345-1.jpg</picture>
        <picture>https://myshop.ru/images/12345-2.jpg</picture>
        <stickers>0,1</stickers>
        <description>Флагманский смартфон Samsung Galaxy S23 с процессором Snapdragon 8 Gen 2.</description>
        <vendor>Samsung</vendor>
        <vendorCode>SM-S911BZKDEUC</vendorCode>
        <model>Galaxy S23</model>
        <oldprice>69990</oldprice>
              <count>15</count>
        <rating>4.8</rating>
        <priority>150</priority>
        <min_quantity>1</min_quantity>
        <multiplicity>1</multiplicity>
        <keyword>самсунг галакси смартфон телефон android</keyword>
        <location>Москва, склад №1</location>
        <barcode>8806094732345</barcode>
        <param name="Цвет">Черный</param>
        <param name="Память">128 ГБ</param>
        <param unit="дюйм" name="Диагональ экрана">6.1</param>
        <param name="Операционная система">Android</param>
        <param unit="МП" name="Камера">50</param>
        <param unit="г" name="Вес">168</param>
        <regionData>
          <region id="604">
            <url>https://msk.myshop.ru/product/12345</url>
            <price>59990</price>
            <oldprice>69990</oldprice>
            <available>true</available>
            <count>15</count>
            <desc>Флагманский смартфон Samsung Galaxy S23. Доставка по Москве за 1 день</desc>
            <weight>10</weight>
            <stickers>0,1</stickers>
          </region>
          <region id="699">
            <url>https://spb.myshop.ru/product/12345</url>
            <price>58990</price>
            <oldprice>68990</oldprice>
            <available>true</available>
            <count>8</count>
            <weight>5</weight>
            <stickers>1</stickers>
          </region>
        </regionData>
      </offer>

      <!-- Ноутбук -->
      <offer id="12346" available="true">
        <name>Ноутбук Apple MacBook Pro 14</name>
        <url>https://myshop.ru/product/12346</url>
        <price>189990</price>
        <currencyId>RUB</currencyId>
        <categoryId>3</categoryId>
        <picture>https://myshop.ru/images/12346.jpg</picture>
        <stickers>2</stickers>
        <description>Профессиональный ноутбук с чипом M2</description>
        <vendor>Apple</vendor>
        <model>MacBook Pro 14" M2</model>
        <count>5</count>
        <rating>5.0</rating>
        <param name="Процессор">Apple M2</param>
        <param name="Память">16 ГБ</param>
        <param name="Накопитель">512 ГБ SSD</param>
        <param unit="дюйм" name="Диагональ экрана">14</param>
        <param name="Цвет">Серый космос</param>
        <param unit="кг" name="Вес">1.6</param>
      </offer>
    </offers>
  </shop>
</yml_catalog>

6. Поиск по регионам

Для организации мультирегионального поиска используется элемент <regionData>, который позволяет указать разные цены, наличие и URL товара для каждого региона.

Структура:

<regionData>
  <region id="604">
    <url>https://site.ru/catalog/p/234123efsdgwer/</url>
    <price>23540</price>
    <oldprice>29000</oldprice>
    <available>true</available>
    <count>42</count>
    <desc>Казан афганский с доставкой по Москве за 1 день</desc>
    <weight>10</weight>
    <stickers>0,1</stickers>
  </region>
  <region id="699">
    <url>https://site.ru/catalog/p/er6345456gwer/</url>
    <price>22500</price>
    <oldprice>28000</oldprice>
    <available>false</available>
    <count>11</count>
    <stickers>2</stickers>
  </region>
  <region id="647">
    <url>https://site.ru/catalog/p/er312123dgwer/</url>
    <price>22600</price>
    <oldprice>27000</oldprice>
    <available>true</available>
    <count>13</count>
    <weight>5</weight>
    <stickers>0</stickers>
  </region>
</regionData>

Элемент region

Каждый регион описывается отдельным элементом <region>.

Атрибуты элемента region:

Поля элемента region:

Правила:

• Элемент <regionData> размещается внутри <offer>, обычно в конце описания товара
• ID региона должен соответствовать настройкам вашего поддомена
• После настройки необходимо сообщить, какой регион к какому поддомену привязан
• Если товар отсутствует в каком-то регионе — его можно не указывать в <regionData>

Пример товара с региональными данными:

<offer id="12345" available="true">
  <name>Смартфон Samsung Galaxy S23 128GB Black</name>
  <url>https://myshop.ru/product/12345</url>
  <price>59990</price>
  <currencyId>RUB</currencyId>
  <categoryId>2</categoryId>
  <picture>https://myshop.ru/images/12345.jpg</picture>
  <description>Флагманский смартфон Samsung Galaxy S23</description>
  <vendor>Samsung</vendor>

  <regionData>
    <region id="604">
      <url>https://msk.myshop.ru/product/12345</url>
      <price>59990</price>
      <oldprice>69990</oldprice>
      <available>true</available>
      <count>15</count>
      <desc>Флагманский смартфон Samsung Galaxy S23. Доставка по Москве за 1 день</desc>
      <weight>10</weight>
      <stickers>0,1</stickers>
    </region>
    <region id="699">
      <url>https://spb.myshop.ru/product/12345</url>
      <price>58990</price>
      <oldprice>68990</oldprice>
      <available>true</available>
      <count>8</count>
      <weight>5</weight>
      <stickers>1</stickers>
    </region>
    <region id="647">
      <url>https://ekb.myshop.ru/product/12345</url>
      <price>61990</price>
      <oldprice>71990</oldprice>
      <available>false</available>
      <count>0</count>
      <stickers>2</stickers>
    </region>
  </regionData>
</offer>

После интеграции региональных данных свяжитесь с технической поддержкой для настройки привязки ID регионов к поддоменам.

Рекомендации

Обязательно заполняйте:

• name — качественное название с ключевыми характеристиками
• picture — хотя бы одно изображение (лучше несколько)
• description — подробное описание для лучшей индексации
• vendor — производитель/бренд (важно для поиска)
• categoryId — правильная категория товара

Проверьте перед загрузкой:

• Файл в кодировке UTF-8
• Все обязательные поля заполнены
• ID товаров и категорий уникальны
• URL корректные и доступные
• Цены актуальные
• Изображения доступны по указанным URL

Частые ошибки:

• Неверная кодировка (не UTF-8)
• Дубликаты ID товаров
• Некорректные URL (404 ошибки)
• Пустые обязательные поля
• Неверный формат даты в yml_catalog