Выгодные товары в категории

  1. Описание
  2. Входные данные
  3. Выходные данные
  4. Ошибки
  5. Примеры

Описание

GET /categories/{categoryId}/hot-offers

Возвращает список выгодных товаров в указанной категории на Маркете. Товар попадает в список выгодных, если в момент запроса он продается на Маркете дешевле, чем в других маркетплейсах или магазинах.

Каждому товару соответствует своя страница на Маркете — карточка товара. На одной карточке может размещаться несколько вариантов товара. Например, у смартфона могут быть разные цвета, а у чая — разное количество пакетиков. В результатах запроса возвращаются выгодные варианты товаров.

Запрос является регионозависимым, его результаты возвращаются постранично.

URL ресурса:

https://api.content.market.yandex.ru/v3/affiliate/categories/{categoryId}/hot-offers

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

Параметр

Тип

Значение

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

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

Чтобы узнать идентификатор, откройте страницу категории на Маркете и посмотрите на ее URL. Идентификатор — это набор цифр после «...?hid=». Например:

https://market.yandex.ru/catalog--vytiazhki/54935/list?hid=90581
geo_id Int32

Идентификатор региона, в котором нужно найти товары.

Список идентификаторов часто используемых регионов см. в разделе Регионозависимые запросы.

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

Формат выходных данных:

  • json
  • xml

Значение по умолчанию: json.
fields String

Информация о товаре, которую нужно получить (можно перечислить несколько значений через запятую):

  • OFFER_DELIVERY — условия доставки (параметр delivery) вариантов товара, возвращаемых в ответе.
  • OFFER_PHOTO — все изображения (параметры photo и photos) вариантов товара, возвращаемых в ответе.
clid String

Идентификатор площадки.

Указанный идентификатор CLID добавляется в URL, возвращаемые в ответе, в виде query-параметра: {url}&clid=1234567&.... По умолчанию используется идентификатор площадки, для которой выдавался авторизационный ключ.

Идентификатор можно узнать у персонального менеджера. Если вы являетесь партнером Яндекс.Маркета, идентификатор также можно найти в интерфейсе Яндекс.Дистрибуции, на странице Продукты.
vid String

Дополнительный идентификатор для ссылок — строка длиной до 150 символов только из латинских букв, цифр и специальных знаков: ., :, -, _.

Указанный идентификатор добавляется в URL, возвращаемые в ответе, в виде query-параметра: {url}&vid=review&.... С его помощью можно отслеживать статистику по отдельной ссылке или сравнивать статистику по одинаковым ссылкам на разных страницах.

Подробнее см. в разделе Дополнительный идентификатор инструмента VID Справки партнерской сети Яндекс.Маркета.
page Int8

Номер страницы результатов: от 1 до 50.

Значение по умолчанию: 1.
count Int8

Количество результатов на странице: от 1 до 30.

Значение по умолчанию: 10.

Параметр

Тип

Значение

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

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

Чтобы узнать идентификатор, откройте страницу категории на Маркете и посмотрите на ее URL. Идентификатор — это набор цифр после «...?hid=». Например:

https://market.yandex.ru/catalog--vytiazhki/54935/list?hid=90581
geo_id Int32

Идентификатор региона, в котором нужно найти товары.

Список идентификаторов часто используемых регионов см. в разделе Регионозависимые запросы.

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

Формат выходных данных:

  • json
  • xml

Значение по умолчанию: json.
fields String

Информация о товаре, которую нужно получить (можно перечислить несколько значений через запятую):

  • OFFER_DELIVERY — условия доставки (параметр delivery) вариантов товара, возвращаемых в ответе.
  • OFFER_PHOTO — все изображения (параметры photo и photos) вариантов товара, возвращаемых в ответе.
clid String

Идентификатор площадки.

Указанный идентификатор CLID добавляется в URL, возвращаемые в ответе, в виде query-параметра: {url}&clid=1234567&.... По умолчанию используется идентификатор площадки, для которой выдавался авторизационный ключ.

Идентификатор можно узнать у персонального менеджера. Если вы являетесь партнером Яндекс.Маркета, идентификатор также можно найти в интерфейсе Яндекс.Дистрибуции, на странице Продукты.
vid String

Дополнительный идентификатор для ссылок — строка длиной до 150 символов только из латинских букв, цифр и специальных знаков: ., :, -, _.

Указанный идентификатор добавляется в URL, возвращаемые в ответе, в виде query-параметра: {url}&vid=review&.... С его помощью можно отслеживать статистику по отдельной ссылке или сравнивать статистику по одинаковым ссылкам на разных страницах.

Подробнее см. в разделе Дополнительный идентификатор инструмента VID Справки партнерской сети Яндекс.Маркета.
page Int8

Номер страницы результатов: от 1 до 50.

Значение по умолчанию: 1.
count Int8

Количество результатов на странице: от 1 до 30.

Значение по умолчанию: 10.

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

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

{
  "status": "{enum}",
  "context": 
  {
    "id": "{string}",
    "time": "{date}",
    "link": "{string}",
    "marketUrl": "{string}",
    "region": 
    {
      "id": {int32},
      "name": "{string}",
      "type": "{enum}",
      "childCount": {int32},
      "country": 
      {
        "id": {int32},
        "name": "{string}",
        "type": "{enum}",
        "childCount": {int32}
      }
    },
    "currency": 
    {
      "id": "{string}",
      "name": "{string}"
    },
    "page":
    {
      "number": {int32},
      "count": {int32}
    }
  },
  "offers": 
  [
    {
      "sku": "{string}",
      "name": "{string}",
      "url": "{string}",
      "description": "{string}",
      "price":
      {
        "value": "{string}"
      },
      "photo": 
      {
        "width": {int32},
        "height": {int32},
        "url": "{string}"
      },
      "photos":
      [
        {
          "width": {int32},
          "height": {int32},
          "url": "{string}"
        },
        ...
      ],
      "delivery":
      {
        "brief": "{string}",
        "price":
        {
          "value": "{string}",
          "base": "{string}"
        }
      }
    },
    ...
  ]
}

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

Параметр для формата JSON Параметр для формата XML Тип Описание
result

Ответ.

Параметр возвращается только для формата XML.
Параметры, вложенные в result
status status

Enum

Статус выполнения запроса:

  • OK — запрос выполнен успешно.

  • ERROR — произошла ошибка.

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

Информация о запросе.
offers offers

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

String

Идентификатор запроса.

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

Date

Дата и время выполнения запроса.

Формат даты: ISO 8601 с миллисекундами и смещением относительно UTC. Например, 2017-11-21T00:00:00.000+03:00.

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

String

URL страницы запроса на Маркете.

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

String

URL Маркета.

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

Регион, для которого возвращаются данные.
currency currency

Валюта, в которой указаны цены в ответе.
page page

Информация о страницах результатов.
Параметры, вложенные в region
id id

Int32

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

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

String

Название региона.

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

Enum

Тип региона:

  • CONTINENT — континент.

  • REGION — регион.

  • COUNTRY — страна.

  • COUNTRY_DISTRICT — федеральный округ.

  • SUBJECT_FEDERATION — субъект федерации.

  • CITY — город.

  • VILLAGE — село.

  • CITY_DISTRICT — район города.

  • METRO_STATION — станция метро.

  • SUBJECT_FEDERATION_DISTRICT — район субъекта федерации.

  • AIRPORT — аэропорт.

  • OVERSEAS_TERRITORY — отдельная территория какого‑либо государства, расположенная в другой части света (например, Ангилья, Гренландия, Бермудские острова и т. д.).

  • SECONDARY_DISTRICT — район города второго уровня (например, для ВАО Москвы районами второго уровня являются Измайлово, Новокосино, Перово и т. д.).

  • MONORAIL_STATION — станция монорельса.

  • RURAL_SETTLEMENT — сельское поселение.

  • OTHER — другой тип населенного пункта.

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

Int32

Количество дочерних регионов.

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

Страна, в которой расположен регион.
Параметры, вложенные в country
id id

Int32

Идентификатор страны.

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

String

Название страны.

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

Enum

Тип региона:

  • COUNTRY — страна.

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

Int32

Количество дочерних регионов.

Для формата XML является атрибутом параметра country.
Параметры, вложенные в currency
id id

Enum

Код валюты:

  • RUR — российский рубль.
name name

String

Название валюты.
Параметры, вложенные в page
number number

Int32

Порядковый номер текущей страницы результатов.

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

Int32

Количество товаров на текущей странице результатов.

Для формата XML является атрибутом параметра page.
Параметры, вложенные в offers
offer

Информация о товаре.

Параметр возвращается только для формата XML.
Параметры, вложенные в offers / offer
sku sku String

Идентификатор варианта товара (SKU на Маркете).

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

String

Название варианта товара.

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

String

URL варианта товара на Маркете.

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

String

Описание варианта товара.
price price

Информация о цене варианта товара.
photo photo

Основное изображение варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
photos photos

Все изображения варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
delivery delivery

Информация о доставке варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.
Параметры, вложенные в price (offer)
value value

String

Цена варианта товара. Если на вариант товара действует скидка, указана цена со скидкой.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
Параметры, вложенные в photo
width width

Int32

Ширина изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

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

Int32

Высота изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

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

String

URL изображения.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
Параметры, вложенные в photos
photo

Изображение варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
Параметры, вложенные в photos / photo
width width

Int32

Ширина изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

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

Int32

Высота изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

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

String

URL изображения.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
Параметры, вложенные в delivery
brief brief

String

Краткое описание условий доставки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

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

Int32

Информация о стоимости доставки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Для формата XML является атрибутом параметра delivery.
Параметры, вложенные в price (delivery)
value value

String

Стоимость доставки. Если на доставку действует скидка, указана цена со скидкой.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

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

String

Стоимость доставки без скидки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY и на доставку действует скидка.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
Параметр для формата JSON Параметр для формата XML Тип Описание
result

Ответ.

Параметр возвращается только для формата XML.
Параметры, вложенные в result
status status

Enum

Статус выполнения запроса:

  • OK — запрос выполнен успешно.

  • ERROR — произошла ошибка.

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

Информация о запросе.
offers offers

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

String

Идентификатор запроса.

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

Date

Дата и время выполнения запроса.

Формат даты: ISO 8601 с миллисекундами и смещением относительно UTC. Например, 2017-11-21T00:00:00.000+03:00.

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

String

URL страницы запроса на Маркете.

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

String

URL Маркета.

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

Регион, для которого возвращаются данные.
currency currency

Валюта, в которой указаны цены в ответе.
page page

Информация о страницах результатов.
Параметры, вложенные в region
id id

Int32

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

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

String

Название региона.

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

Enum

Тип региона:

  • CONTINENT — континент.

  • REGION — регион.

  • COUNTRY — страна.

  • COUNTRY_DISTRICT — федеральный округ.

  • SUBJECT_FEDERATION — субъект федерации.

  • CITY — город.

  • VILLAGE — село.

  • CITY_DISTRICT — район города.

  • METRO_STATION — станция метро.

  • SUBJECT_FEDERATION_DISTRICT — район субъекта федерации.

  • AIRPORT — аэропорт.

  • OVERSEAS_TERRITORY — отдельная территория какого‑либо государства, расположенная в другой части света (например, Ангилья, Гренландия, Бермудские острова и т. д.).

  • SECONDARY_DISTRICT — район города второго уровня (например, для ВАО Москвы районами второго уровня являются Измайлово, Новокосино, Перово и т. д.).

  • MONORAIL_STATION — станция монорельса.

  • RURAL_SETTLEMENT — сельское поселение.

  • OTHER — другой тип населенного пункта.

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

Int32

Количество дочерних регионов.

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

Страна, в которой расположен регион.
Параметры, вложенные в country
id id

Int32

Идентификатор страны.

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

String

Название страны.

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

Enum

Тип региона:

  • COUNTRY — страна.

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

Int32

Количество дочерних регионов.

Для формата XML является атрибутом параметра country.
Параметры, вложенные в currency
id id

Enum

Код валюты:

  • RUR — российский рубль.
name name

String

Название валюты.
Параметры, вложенные в page
number number

Int32

Порядковый номер текущей страницы результатов.

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

Int32

Количество товаров на текущей странице результатов.

Для формата XML является атрибутом параметра page.
Параметры, вложенные в offers
offer

Информация о товаре.

Параметр возвращается только для формата XML.
Параметры, вложенные в offers / offer
sku sku String

Идентификатор варианта товара (SKU на Маркете).

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

String

Название варианта товара.

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

String

URL варианта товара на Маркете.

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

String

Описание варианта товара.
price price

Информация о цене варианта товара.
photo photo

Основное изображение варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
photos photos

Все изображения варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
delivery delivery

Информация о доставке варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.
Параметры, вложенные в price (offer)
value value

String

Цена варианта товара. Если на вариант товара действует скидка, указана цена со скидкой.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
Параметры, вложенные в photo
width width

Int32

Ширина изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

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

Int32

Высота изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

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

String

URL изображения.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
Параметры, вложенные в photos
photo

Изображение варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
Параметры, вложенные в photos / photo
width width

Int32

Ширина изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

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

Int32

Высота изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

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

String

URL изображения.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
Параметры, вложенные в delivery
brief brief

String

Краткое описание условий доставки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

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

Int32

Информация о стоимости доставки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Для формата XML является атрибутом параметра delivery.
Параметры, вложенные в price (delivery)
value value

String

Стоимость доставки. Если на доставку действует скидка, указана цена со скидкой.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

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

String

Стоимость доставки без скидки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY и на доставку действует скидка.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

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

Ошибки

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

Примеры

Запрос:

curl -i \
-H 'Authorization: <ключ>' \
'https://api.content.market.yandex.ru/v3/affiliate'\
'/categories/90589/hot-offers'\
'?geo_id=213'\
'&count=2'\
'&fields=OFFER_DELIVERY,OFFER_PHOTO'\
'&format=json'

Ответ:

HTTP/1.1 200 OK
Date: Tue, 09 Jun 2020 09:27:38 GMT
Content-Type: application/json;charset=utf-8
...

{
  "status": "OK",
  "context": 
  {
    "region": 
    {
      "id": 213,
      "name": "Москва",
      "country": 
      {
        "id": 225,
        "name": "Россия",
        "type": "COUNTRY",
        "childCount": 10
      },
      "type": "CITY",
      "childCount": 14
    },
    "currency": 
    {
      "id": "RUR",
      "name": "руб."
    },
    "page": 
    {
      "number": 1,
      "count": 2
    },
    "id": "1591644093771/74fd06d0c97eb3727570d18497a70500",
    "time": "2020-06-09T12:27:38.877+03:00",
    "link": 
      "https://market.yandex.ru/product/100423045906?pp=1930&clid=2310490&mclid=1003&distr_type=7&hid=90589&offerid=WjoAPgFsqbQOOz4AH0tNAQ&cpc=c7N_k-T71Q0XlNhAhbse_B7efV21bTyjTPlDWyQ9xuhs6B6bFP3pLAH4odPJzGNhE6aZzEscESeS1zut-2bL8ke5Cvp_8Vf23YLTJo-8TZXnVhJndH0jQZyTQPQ_T30q&lr=213",
    "marketUrl": "https://market.yandex.ru?pp=1930&clid=2396889&mclid=1003&distr_type=7"
  },
  "offers": 
  [
    {
      "sku": "100423045906",
      "name": "Кофеварка Braun KF 3100 белый",
      "description": "",
      "price": 
      {
        "value": "1632"
      },
      "url": 
        "https://market.yandex.ru/product/100423045906?pp=1930&clid=2310490&mclid=1003&distr_type=7&hid=90589&offerid=WjoAPgFsqbQOOz4AH0tNAQ&cpc=c7N_k-T71Q0XlNhAhbse_B7efV21bTyjTPlDWyQ9xuhs6B6bFP3pLAH4odPJzGNhE6aZzEscESeS1zut-2bL8ke5Cvp_8Vf23YLTJo-8TZXnVhJndH0jQZyTQPQ_T30q&lr=213",
      "photo": 
      {
        "width": 387,
        "height": 701,
        "url": "https://avatars.mds.yandex.net/get-mpic/331398/img_id5269222912410020309.jpeg/orig"
      },
      "delivery": 
      {
        "price": 
        {
          "value": "249"
        },
        "brief": "в Москву — 249 руб."
      },
      "photos": 
      [
        {
          "width": 387,
          "height": 701,
          "url": "https://avatars.mds.yandex.net/get-mpic/331398/img_id5269222912410020309.jpeg/orig"
        },
        {
          "width": 481,
          "height": 701,
          "url": "https://avatars.mds.yandex.net/get-mpic/1883514/img_id4974599352142315682.jpeg/orig"
        },
        {
          "width": 552,
          "height": 701,
          "url": "https://avatars.mds.yandex.net/get-mpic/397397/img_id2684640246186853663.jpeg/orig"
        }
      ]
    },
    {
      "sku": "100807553520",
      "name": "Кофемашина Gretti NR-101 stainless steel",
      "description": "",
      "price": 
      {
        "value": "6500"
      },
      "url": 
        "https://market.yandex.ru/product/100807553520?pp=1930&clid=2310490&mclid=1003&distr_type=7&hid=90589&offerid=1vYo7dlp55S-7V9hinEs0Q&cpc=553EUQW0AT6hFQmrPPe6fZtfWAu2f-R1BxUIpD2vb_H1SN2qUA02fwUYoEj8ZvXU_TaV00vYVyYoeytRmMt39YYdMIrptTdBpphGYL75kk0yc4eAT4EVog3E0-X5U8jd&lr=213",
      "photo": 
      {
        "width": 521,
        "height": 636,
        "url": "https://avatars.mds.yandex.net/get-mpic/1911047/img_id954423418041491828.jpeg/orig"
      },
      "delivery": 
      {
        "price": 
        {
          "value": "0",
          "base": "249"
        },
        "brief": "в Москву — бесплатно, возможен самовывоз"
      },
      "photos": 
      [
        {
          "width": 521,
          "height": 636,
          "url": "https://avatars.mds.yandex.net/get-mpic/1911047/img_id954423418041491828.jpeg/orig"
        }
      ]
    }
  ]
}