Рекомендации по популярным запросам в поиске Яндекс.Маркета

Описание

POST /campaigns/{campaignId}/bids/recommended/top/market-search

Возвращает:

  • список популярных запросов в поиске Яндекс.Маркета, рекомендованных для предложения;

  • рекомендованные значения ставок.

Рекомендации возвращаются для размещения среди первых 12 предложений магазинов в поиске Яндекс.Маркета и рассчитываются для региона, в котором находится магазин.

Внимание.

Возвращаемые ставки являются прогнозируемыми и не гарантируют попадание предложения на указанное место размещения.

Передача списка предложений, для которых необходимо получить рекомендации, осуществляется в теле POST-запроса. Действует ограничение на количество предложений в одном запросе: 500 предложений.

URL ресурса:

https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/bids/recommended/top/market-search.[format]

Входные данные

Параметр

Тип

Значение

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

campaignId

Int64

Идентификатор магазина.

Структура тела POST-запроса:

<offers>
  <offer feed-id="{int64}" id="{string}"/>
  ...
</offers>

В теле POST-запроса передаются следующие параметры:

Параметр для формата XML

Параметр для формата JSON

Тип

Значение

offers offers

Список предложений.

Параметры, вложенные в offers

offer

Предложение.

Параметр используется только для формата XML.

Параметры, вложенные в offer / offers

feed-id feedId Int64

Идентификатор прайс-листа, содержащего предложение.

Для формата XML является атрибутом параметра offer.

id id String

Идентификатор предложения из прайс-листа.

Внимание. Ресурс поддерживает идентификацию только по идентификатору предложения.

Для формата XML является атрибутом параметра offer.

Выходные данные

Структура выходных данных приведена ниже. Порядок следования параметров не гарантируется.

<response>
  <result>
    <top-recommendations>
      <offer bid="{double}" dont-pull-up-bids="{boolean}" feed-id="{int64}" min-bid="{double}" offer-id="{string}">
        <name>{string}</name>
        <queries>
          <query average-offer-pos="{int32}" current-pos-all="{int32}" model-count="{int32}" offer-show-count="{int32}" query-show-count="{int32}" text="{string}" type="{enum}">
            <positions>
              <position bid="{double}" error="{enum}" pos="{int32}"/>
              ...
            </positions>
          </query>
          ...
        </queries>
      </offer>
      ...
    </top-recommendations>
  </result>
</response>

Описание параметров:

Параметр для формата XML

Параметр для формата JSON

Тип

Значение

response

Ответ.

Параметр выводится только для формата XML.

Параметры, вложенные в response

result result

Результат работы метода.

Параметры, вложенные в result

top-recommendations topRecommendations

Список популярных запросов в поиске Яндекс.Маркета и рекомендаций ставок для размещения предложения.

Параметры, вложенные в top-recommendations / topRecommendations

offer

Информация о примененных ставках и рекомендациях ставок для предложения.

Параметр выводится только для формата XML.

Параметры, вложенные в offer / topRecommendations

bid bid Double

Примененная общая ставка, в условных единицах.

Для формата XML является атрибутом параметра offer.

dont-pull-up-bids dontPullUpBids Boolean

Автоматическое повышение ставок bid и cbid до минимальных:

  • true — отключено. Будут действовать установленные магазином ставки.
    Примечание. Если ставки bid и cbid установлены ниже минимальных, предложение не будет показываться.
  • false — включено. Если установлена ставка ниже минимальной, Яндекс.Маркет автоматически поднимет ее до минимальной.

Для формата XML является атрибутом параметра offer.

feed-id feedId Int64

Идентификатор прайс-листа, содержащего предложение.

Для формата XML является атрибутом параметра offer.

min-bid minBid Double

Минимальный размер применяемой общей ставки для данного предложения в поиске Яндекс.Маркета.

Для формата XML является атрибутом параметра offer.

offer-id offerId String

Идентификатор предложения из прайс-листа.

Для формата XML является атрибутом параметра offer.

name name String

Название предложения.

queries queries

Параметр включает:

  • список популярных запросов в поиске Яндекс.Маркета, рекомендованных для предложения;

  • рекомендованные ставки для размещения предложения.

Минимально возможное значение: 0.

Максимально возможное значение: 6 (по 3 запроса для каждого типа статистики, указанного в параметре type).

Параметры, вложенные в queries

query

Рекомендованный для предложения популярный запрос в поиске Яндекс.Маркета и ставки.

Параметр выводится только для формата XML.

Параметры, вложенные в query / queries

average-offer-pos averageOfferPos Int32

Средняя позиция предложения в поиске Яндекс.Маркета по данному запросу в течение предыдущей недели с текущей даты.

Для формата XML является атрибутом параметра query.

current-pos-all currentPosAll Int32

Позиция в блоке предложений магазинов в поиске Яндекс.Маркета. Блок с предложениями магазинов расположен после блока с карточками моделей. Если параметр не выдается или имеет значение 0 — предложение не попало в число первых 12 из-за низкой релевантности запросу пользователя.

Для формата XML является атрибутом параметра query.

model-count modelCount Int32

Количество позиций в поиске Яндекс.Маркета, занятых карточками моделей. Блок с карточками расположен над блоком с предложениями магазинов.

Например, если по запросу нашлось три карточки модели, предложение сможет занять в поиске Яндекс.Маркета позицию, начиная с четвертой. Однако, это будет первая позиция в блоке с предложениями магазинов.

Для формата XML является атрибутом параметра query.

offer-show-count offerShowCount Int32

Количество показов предложения по указанному запросу в поиске Яндекс.Маркета в течение предыдущей недели с текущей даты.

Для формата XML является атрибутом параметра query.

query-show-count queryShowCount Int32

Сколько раз пользователи вводили указанный запрос, по которому показывалось предложение в поиске Яндекс.Маркета в течение предыдущей недели с текущей даты.

Для формата XML является атрибутом параметра query.

text text String

Текст запроса в поиске Яндекс.Маркета, рекомендуемый для данного предложения.

Для формата XML является атрибутом параметра query.

type type Enum

Тип статистики, на основе которой выводятся популярные поисковые запросы, рекомендованные для предложения.

Возможные значения:

  • TOP_OFFER — рекомендация построена на основе статистики показа предложения пользователям на поиске Яндекс.Маркета. Чем больше значение параметра offer-show-count, тем чаще предложение показывалось в ответ на указанный поисковый запрос.

  • TOP_ALL — рекомендация построена на основе статистики использования запросов в поиске Яндекс.Маркета (те запросы, по которым показывалось предложение). Чем больше значение параметра query-show-count, тем популярнее указанный поисковый запрос среди пользователей.

Для формата XML является атрибутом параметра query.

positions positions

Список рекомендаций ставок для предложения магазина для размещения в поиске Яндекс.Маркета. Рекомендации выводятся для первых 12 позиций.

Параметры, вложенные в positions

position

Рекомендация ставки для предложения магазина для размещения по соответствующим популярным запросам в поиске Яндекс.Маркета. Рекомендации выводятся для первых 12 позиций.

При выставлении размера ставки согласно данной рекомендации высокая позиция предложения в поиске Яндекс.Маркета не всегда достижима. В первую очередь на позицию предложения в поиске Яндекс.Маркета влияет релевантность запросу пользователя.

Параметр выводится только для формата XML.

Параметры, вложенные в position / positions

bid bid Double

Рекомендованная общая ставка для достижения указанной позиции на поиске Яндекс.Маркета, в условных единицах.

Для формата XML является атрибутом параметра position.

error error Enum

Описание произошедшей ошибки. Параметр выводится только в случае возникновения ошибки.

Возможные значения:

  • UNKNOWN — указанная в запросе позиция недостижима по неизвестной причине. Обратитесь в службу поддержки.

  • UNREACHABLE — указанная в запросе позиция недостижима.

Для формата XML является атрибутом параметра position.

pos pos Int32

Номер позиции предложения, для которой указывается рекомендация.

Для формата XML является атрибутом параметра position.

Описание ошибок

В случае ошибки сервер возвращает HTTP-код ответа и краткое описание ошибки.

Ошибки, содержащие характерные для данного метода краткие описания:

Описание

Пояснение

Способ возможного решения

Ошибка 400 Bad Request

Current offer identification type is: 'TITLE'

Идентификация ставок не соответствует установленному режиму. Ресурс поддерживает идентификацию только по идентификатору предложения.

При необходимости смените режим идентификации в личном кабинете.

Feed should be specified

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

Проверьте корректность передаваемых в запросе данных.

Too many offers: 'offersCount'

В запросе указано больше 500 предложений.

Уменьшите количество передаваемых предложений.

Ошибка 404 Not Found

Feed not found: 'feedId'

В параметре feed-id передан некорректный идентификатор прайс-листа.

Проверьте корректность данных в запросе.

Ограничения

Для запросов PUT /campaigns/{campaignId/auction/bids, POST /campaigns/{campaignId}/auction/recommendations/bids, POST /campaigns/{campaignId}/bids/recommended/top/market-search и PUT /campaigns/{campaignId}/auction/recommendations/bids, а также устаревших PUT /campaigns/{campaignId}/bids и POST /campaigns/{campaignId}/bids/recommended действует групповое ресурсное ограничение. Ограничение вводится на суммарное количество предложений, по которым при помощи этих методов выставлены ставки или получены рекомендации.

Объем запросов к ресурсам, который возможно выполнить в течение суток, рассчитывается индивидуально и зависит от количества предложений магазина на карточках товаров.

Примечание.

Количество предложений считается по данным за последние семь дней (не включая сегодня).

Для новых магазинов, еще не разместивших предложения, ограничение равно 0 и пересчитывается на следующий день после размещения первых предложений.

Примеры

Пример запроса:

curl -i -H 'Content-Type: application/xml'-X POST 'https://api.partner.market.yandex.ru/v2/campaigns/10001/bids/recommended/top/market-search.xml'

Тело POST-запроса:

-d '<offers>
  <offer feed-id="789101" id="123456"/>
  <offer feed-id="789101" id="112131"/>
</offers>'

Пример ответа:

HTTP/1.1 200 OK
Date: Mon, 10 Jul 2017 00:42:42 GMT
Content-Type: application/xml;charset=utf-8
...

<response>
  <result>
    <top-recommendations>
      <offer bid="0.12" feed-id="789101" min-bid="0.12" offer-id="123456">
        <name>Lenovo G5045 80E301Q9RK black 15.6 HD E1-6010 / 2 Gb / 500 Gb / noDVD / W10</name>
        <queries>
          <query average-offer-pos="47" current-pos-all="1" model-count="0" offer-show-count="17" query-show-count="2478" text="9RK" type="TOP_OFFER">
            <positions>
              <position bid="0.12" pos="1"/>
              <position bid="0.12" pos="2"/>
              <position bid="0.12" pos="3"/>
              <position bid="0.12" pos="4"/>
              <position bid="0.12" pos="5"/>
              <position bid="0.12" pos="6"/>
              <position bid="0.12" pos="7"/>
              <position bid="0.12" pos="8"/>
              <position bid="0.12" pos="9"/>
              <position bid="0.12" pos="10"/>
              <position bid="0.12" pos="11"/>
              <position bid="0.12" pos="12"/>
            </positions>
          </query>
          <query average-offer-pos="2" current-pos-all="1" model-count="0" offer-show-count="22" query-show-count="50" text="80E301Q9RK" type="TOP_OFFER">
            <positions>
              <position bid="0.12" pos="1"/>
              <position bid="0.12" pos="2"/>
              <position bid="0.12" pos="3"/>
              <position bid="0.12" pos="4"/>
              <position bid="0.12" pos="5"/>
              <position bid="0.12" pos="6"/>
              <position bid="0.12" pos="7"/>
              <position bid="0.12" pos="8"/>
              <position bid="0.12" pos="9"/>
              <position bid="0.12" pos="10"/>
              <position bid="0.12" pos="11"/>
              <position bid="0.12" pos="12"/>
            </positions>
          </query>
        </queries>
      </offer>
      <offer bid="0.13" feed-id="789101" min-bid="0.13" offer-id="112131">
        <name>Компьютер C400008Ц-NORBEL Office Base ATI-Intel Core i3 4170 / H81M-P33 / 4 Gb / 500 Gb</name>
        <queries>
          <query average-offer-pos="10" current-pos-all="10" model-count="0" offer-show-count="14" query-show-count="267" text="H81M-P33" type="TOP_ALL">
            <positions>
              <position bid="0.68" pos="1"/>
              <position bid="0.68" pos="2"/>
              <position bid="0.63" pos="3"/>
              <position bid="0.60" pos="4"/>
              <position bid="0.55" pos="5"/>
              <position bid="0.52" pos="6"/>
              <position bid="0.52" pos="7"/>
              <position bid="0.40" pos="8"/>
              <position bid="0.18" pos="9"/>
              <position bid="0.13" pos="10"/>
              <position bid="0.13" pos="11"/>
              <position bid="0.13" pos="12"/>
            </positions>
          </query>
          <query average-offer-pos="10" current-pos-all="9" model-count="0" offer-show-count="4" query-show-count="51" text="H81M-P" type="TOP_ALL">
            <positions>
              <position bid="1.00" pos="1"/>
              <position bid="0.99" pos="2"/>
              <position bid="0.61" pos="3"/>
              <position bid="0.59" pos="4"/>
              <position bid="0.51" pos="5"/>
              <position bid="0.49" pos="6"/>
              <position bid="0.49" pos="7"/>
              <position bid="0.27" pos="8"/>
              <position bid="0.13" pos="9"/>
              <position bid="0.13" pos="10"/>
              <position bid="0.13" pos="11"/>
              <position bid="0.13" pos="12"/>
            </positions>
          </query>
          <query average-offer-pos="9" model-count="0" offer-show-count="7" query-show-count="73" text="H81M-P33 PLUS" type="TOP_ALL">
            <positions>
              <position error="UNREACHABLE" pos="1"/>
              <position error="UNREACHABLE" pos="2"/>
              <position bid="0.49" pos="3"/>
              <position bid="0.41" pos="4"/>
              <position bid="0.41" pos="5"/>
              <position bid="0.41" pos="6"/>
              <position bid="0.38" pos="7"/>
              <position bid="0.34" pos="8"/>
              <position bid="0.13" pos="9"/>
              <position bid="0.13" pos="10"/>
              <position bid="0.13" pos="11"/>
              <position bid="0.13" pos="12"/>
            </positions>
          </query>
          <query average-offer-pos="10" current-pos-all="10" model-count="0" offer-show-count="14" query-show-count="267" text="H81M-P33" type="TOP_OFFER">
            <positions>
              <position bid="0.68" pos="1"/>
              <position bid="0.68" pos="2"/>
              <position bid="0.63" pos="3"/>
              <position bid="0.60" pos="4"/>
              <position bid="0.55" pos="5"/>
              <position bid="0.52" pos="6"/>
              <position bid="0.52" pos="7"/>
              <position bid="0.40" pos="8"/>
              <position bid="0.18" pos="9"/>
              <position bid="0.13" pos="10"/>
              <position bid="0.13" pos="11"/>
              <position bid="0.13" pos="12"/>
            </positions>
          </query>
          <query average-offer-pos="10" current-pos-all="9" model-count="0" offer-show-count="4" query-show-count="51" text="H81M-P" type="TOP_OFFER">
            <positions>
              <position bid="1.00" pos="1"/>
              <position bid="0.99" pos="2"/>
              <position bid="0.61" pos="3"/>
              <position bid="0.59" pos="4"/>
              <position bid="0.51" pos="5"/>
              <position bid="0.49" pos="6"/>
              <position bid="0.49" pos="7"/>
              <position bid="0.27" pos="8"/>
              <position bid="0.13" pos="9"/>
              <position bid="0.13" pos="10"/>
              <position bid="0.13" pos="11"/>
              <position bid="0.13" pos="12"/>
            </positions>
          </query>
          <query average-offer-pos="9" model-count="0" offer-show-count="7" query-show-count="73" text="H81M-P33 PLUS" type="TOP_OFFER">
            <positions>
              <position error="UNREACHABLE" pos="1"/>
              <position error="UNREACHABLE" pos="2"/>
              <position bid="0.49" pos="3"/>
              <position bid="0.41" pos="4"/>
              <position bid="0.41" pos="5"/>
              <position bid="0.41" pos="6"/>
              <position bid="0.38" pos="7"/>
              <position bid="0.34" pos="8"/>
              <position bid="0.13" pos="9"/>
              <position bid="0.13" pos="10"/>
              <position bid="0.13" pos="11"/>
              <position bid="0.13" pos="12"/>
            </positions>
          </query>
        </queries>
      </offer>
    </top-recommendations>
  </result>
</response>