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

Описание

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}" cbid="{double}" feed-id="{int64}" min-bid="{double}" min-cbid="{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.

cbid cbid Double

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

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

feed-id feedId Int64

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

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

min-bid minBid Double

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

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

min-cbid minCbid 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'

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

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

Ограничения

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

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

  • количество предложений на карточках моделей Яндекс.Маркета.

Примечание.

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

Для новых магазинов, еще не разместивших предложения, ограничение равно 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" cbid="0.01" feed-id="789101" min-bid="0.12" min-cbid="0.01" 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" cbid="0.01" feed-id="789101" min-bid="0.13" min-cbid="0.01" 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>