Руководство разработчика
Ресурсы API

Подбор по параметрам в категории

Описание

GET /{version}/categories/{id}/search

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

Ресурс является регионозависимым и  списочным.

URL ресурса:

https://api.content.market.yandex.ru/{version}/categories/{id}/search

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

ПараметрПоложе­ниеТипОбяза­тельностьОписание
version PATH Enum Да

Версия контентного API.

id PATH Int32 Да

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

fields QUERY Enum list Нет

Поля, которые необходимо показать в выходных данных.

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

  • MODEL_CATEGORY — Информация о категории, к которой относится модель
  • MODEL_DEFAULT_OFFER — информация о товарном предложении по умолчанию для модели в указанном регионе.
  • MODEL_DISCOUNTS — информация о скидках на модель.
  • MODEL_FACTS — Список достоинств и недостатков модели
  • MODEL_FILTER_COLOR — список фильтров по цвету, доступных для отбора модификаций модели.
  • MODEL_MEDIA — информация об отзывах и обзорах на модель.
  • MODEL_NAVIGATION_NODE — информация о навигационном узле дерева категорий Маркета, к которому относится модель.
  • MODEL_OFFERS — информация о товарных предложениях, соотнесенных с моделью, в указанном регионе.
  • MODEL_PHOTO — Изображение модели, используемое как основное изображение на карточке модели
  • MODEL_PHOTOS — все доступные изображения модели.
  • MODEL_PRICE — информация о ценах на модель.
  • MODEL_RATING — иформация о рейтинге и оценках модели.
  • MODEL_SPECIFICATION — характеристики модели.
  • MODEL_VENDOR — информация о производителе.
  • OFFER_ACTIVE_FILTERS — активные фильтры.
  • OFFER_BUNDLE_SETTINGS — минимальный состав заказа.
  • OFFER_CATEGORY — информация о категории предложения.
  • OFFER_DELIVERY — информация о доставке.
  • OFFER_DISCOUNT — скидка.
  • OFFER_OUTLET — информация о точке выдачи производетеля.
  • OFFER_OUTLET_COUNT — Количество точек выдачи предложения
  • OFFER_PHOTO — фото предложения.
  • OFFER_SHOP — магазин от которого поступило предложенение.
  • OFFER_VENDOR — информация о поставщике.
  • SHOP_ORGANIZATION — юридическая информация: юридический и фактический адрес, ОГРН, тип организации, ссылка на реквизиты.
  • SHOP_RATING — рейтинг магазина.

Псевдонимы значений:

  • ALL = Все значения
    Примечание. Значение ALL доступно только для отладки и имеет ограничение по нагрузке – один RPS.
  • MODEL_ALL = MODEL_ACTIVE_FILTERS, MODEL_CATEGORY, MODEL_DEFAULT_OFFER, MODEL_DISCOUNTS, MODEL_FACTS, MODEL_FILTER_COLOR, MODEL_LINK, MODEL_MEDIA, MODEL_NAVIGATION_NODE, MODEL_OFFERS, MODEL_PHOTO, MODEL_PHOTOS, MODEL_PRICE, MODEL_RATING, MODEL_SPECIFICATION, MODEL_VENDOR
  • OFFER_ALL = OFFER_ACTIVE_FILTERS, OFFER_BUNDLE_SETTINGS, OFFER_CATEGORY, OFFER_DELIVERY, OFFER_DISCOUNT, OFFER_LINK, OFFER_OUTLET, OFFER_OUTLET_COUNT, OFFER_PHOTO, OFFER_SHOP, OFFER_VENDOR
  • SHOP_ALL = SHOP_ORGANIZATION, SHOP_RATING
  • STANDARD = MODEL_CATEGORY, MODEL_OFFERS, MODEL_PHOTO, MODEL_PRICE, MODEL_RATING, MODEL_VENDOR, OFFER_CATEGORY, OFFER_DELIVERY, OFFER_OUTLET, OFFER_OUTLET_COUNT, OFFER_PHOTO, OFFER_SHOP, SHOP_RATING

format QUERY Enum Нет

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

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

  • JSON — выходные данные будут сформированы в формате JSON.
  • XML — выходные данные будут сформированы в формате XML.

Значение по умолчанию: JSON.
rs QUERY String Нет

Поле содержащее закодированную информацию о текстовом запросе после редиректа, на которую будет ориентироватся поиск.

shop_regions QUERY Int32 list Нет

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

{filter_id} QUERY String or int64 Нет

Параметры задают условия фильтрации моделей и предложений на модель.

Чтобы задать фильтр необходимо добавить в запрос параметр следующего вида: {filter_id}={filter_value}.

Пример: 7980557=18446744073709529154, где

  • 7980557 — идентификатор фильтра;
  • 18446744073709529154 — значение фильтра.

Получить список фильтров, их идентификаторов и значений для определенной категории можно с помощью ресурса /{version}/categories/{id}/filters.

Значение параметра зависит от типа выбранного фильтра.

Допускается множество параметров.

Ограничения:

  • Для типа фильтра BOOLEAN — допустимые значения фильтра:

    • 1 | T | TRUE | Y | YES — равно TRUE.
    • 0 | F | FALSE | N | NO — равно FALSE.

  • Для типов фильтров ENUM, COLOR, SIZE — {filter_value} определяет список идентификаторов значений фильтра, разделенных запятыми, {value1_id},{value2_id},{value3_id}, где {valueN_id} — идентификатор значения.

  • Для типа фильтра NUMBER — {filter_value} определяет числовой диапазон значений, границы которого разделяются знаком ~ тильда. Форматы значений параметра:

    • {min_value}~ - с тильдой в конце - определяет только нижнюю границу фильтра.
    • ~{max_value} - с тильдой в начале - определяет только верхнюю границу фильтра.
    • {min_value}~{max_value} - с тильдой между числами - определяет нижнюю и вехнюю границы фильтра.

  • Для типа фильтра RADIO — {filter_value} определяет один идентификатор значения фильтра.

  • Для типа фильтра TEXT — {filter_value} определяет текстовую строку поиска.

Параметры для определения региона пользователя для формирования выдачи с учетом региона

Параметр remote_ip имеет более высокий приоритет, чем geo_id.

Если в качестве входных данных задать оба параметра, выдача будет сформирована на основании remote_ip.

geo_id QUERY Int64 Да, если не задан remote_ip

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

remote_ip QUERY String Да, если не задан geo_id

IP-адрес пользователя, по которому определяется его регион. На основании IP-адреса формируется выдача с учетом региона.

Параметры страницы
count QUERY Int32 Нет

Размер страницы (кол-во элементов на странице)

Ограничения:

  • Минимальное значение 1, максимальное значение 30

Значение по умолчанию: 10.
page QUERY Int32 Нет

Номер страницы.

Ограничения:

  • Минимальное значение 1, максимальное значение 50

Значение по умолчанию: 1.
Параметры сортировки
how QUERY Enum Нет

Направление сортировки Значение по-умолчанию null т.к. если параметр не указан, то порядок сортировки зависит от поля по которому сортируем: так по цене сортировка по возрастанию, а по популярности по убыванию.

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

  • ASC — по возрастанию;
  • DESC — по убыванию.

sort QUERY Enum Нет

Определяет, по какому параметру осуществляется сортировка

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

  • DATE — Сначала новые
  • DELIVERY_TIME — По времени доставки
  • DISCOUNT — По скидке (сортировка работает только по убыванию)
  • DISTANCE — По удаленности
  • OPINIONS — По отзывам
  • POPULARITY — По популярности
  • PRICE — По цене
  • QUALITY — По рейтингу
  • RATING — По рейтингу и цене
  • RELEVANCE — По релевантности

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

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

{
  "status
[no-highlight[

Статус обработки запроса.

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

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

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

]no-highlight]
" : "{enum}", "context
[no-highlight[

Контекст обработки запроса.

]no-highlight]
" : { "region
[no-highlight[

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

]no-highlight]
" : { "id
[no-highlight[

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

]no-highlight]
" : {int32}, "name
[no-highlight[

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

]no-highlight]
" : "{string}", "type
[no-highlight[

Тип региона.

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

  • 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 — другой тип населенного пункта.

]no-highlight]
" : "{enum}", "childCount
[no-highlight[

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

]no-highlight]
" : {int32}, "country
[no-highlight[

Страна, к которой относится регион.

Регион

]no-highlight]
" : { Содержимое объекта } }, "currency
[no-highlight[

Валюта запроса.

]no-highlight]
" : { "id
[no-highlight[

Код валюты.

]no-highlight]
" : "{string}", "name
[no-highlight[

Название валюты.

]no-highlight]
" : "{string}" }, "alternateCurrency
[no-highlight[

Альтернативная валюта запроса.

]no-highlight]
" : { "id
[no-highlight[

Код валюты.

]no-highlight]
" : "{string}", "name
[no-highlight[

Название валюты.

]no-highlight]
" : "{string}" }, "page
[no-highlight[

Информация о параметрах страницы запроса.

]no-highlight]
" : { "number
[no-highlight[

Номер страницы.

]no-highlight]
" : {int32}, "count
[no-highlight[

Размер страницы.

]no-highlight]
" : {int32}, "total
[no-highlight[

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

]no-highlight]
" : {int32}, "last
[no-highlight[

Признак последней страницы.

]no-highlight]
" : {boolean}, "totalItems
[no-highlight[

Количество найденных элементов

]no-highlight]
" : {int32} }, "warnings
[no-highlight[

Список предупреждений, возникших при обработке запроса.

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

]no-highlight]
" : [ { "type
[no-highlight[

Тип предупрежедния.

]no-highlight]
" : "{string}", "code
[no-highlight[

Код предупреждения.

]no-highlight]
" : "{string}", "message
[no-highlight[

Сообщение с описанием предупреждения.

]no-highlight]
" : "{string}" }, ... ], "id
[no-highlight[

Уникальный идентификатор запроса.

]no-highlight]
" : "{string}", "time
[no-highlight[

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

]no-highlight]
" : {date}, "link
[no-highlight[

Ссылка на текущий запрос.

]no-highlight]
" : "{string}", "marketUrl
[no-highlight[

Ссылка на Яндекс.Маркет

]no-highlight]
" : "{string}" }, "items
[no-highlight[

Список моделей и/или товарных предложений

Типы:

]no-highlight]
" : [ { "__type" : "model", Содержимое объекта }, { "__type" : "offer", Содержимое объекта }, ... ], "categories
[no-highlight[

Список категорий.

Категория в рез-тах поиска

]no-highlight]
" : [ { Содержимое объекта }, ... ], "sorts
[no-highlight[

Список доступных сортировок

]no-highlight]
" : [ { "text
[no-highlight[

Наименование типа сортировки.

]no-highlight]
" : "{string}", "field
[no-highlight[

Тип сортировки.

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

  • RELEVANCY — сортировка по релевантности.

  • PRICE — сортировка по цене.

  • RATING — сортировка по рейтингу.

  • DISTANCE — сортировка по расстоянию до ближайшей точки продаж (значение доступно только при указании местоположения пользователя).

  • POPULARITY — сортировка по популярности.

  • DISCOUNT — сортировка по размеру скидки.

    Ограничение. Для sort=DISCOUNT возможна только сортировка по убыванию (how=DESC).

  • QUALITY — сортировка по рейтингу.

  • OPINIONS — сортировка по количеству отзывов.

  • DATE — сортировка по дате.

  • DELIVERY_TIME — сортировка по времени доставки.

]no-highlight]
" : "{enum}", "options
[no-highlight[

Доступные варианты для данного типа сортировки.

]no-highlight]
" : [ { "id
[no-highlight[

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

]no-highlight]
" : "{string}", "how
[no-highlight[

Направление сортировки.

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

  • ASC — по возрастанию;

  • DESC — по убыванию.

]no-highlight]
" : "{enum}", "text
[no-highlight[

Наименование данного варианта сортировки

]no-highlight]
" : "{string}" }, ... ] }, ... ] }
<result status
[no-highlight[

Статус обработки запроса.

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

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

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

]no-highlight]
="{enum}"> <context
[no-highlight[

Контекст обработки запроса.

]no-highlight]
id
[no-highlight[

Уникальный идентификатор запроса.

]no-highlight]
="{string}" time
[no-highlight[

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

]no-highlight]
="{date}" link
[no-highlight[

Ссылка на текущий запрос.

]no-highlight]
="{string}" marketUrl
[no-highlight[

Ссылка на Яндекс.Маркет

]no-highlight]
="{string}"> <region
[no-highlight[

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

]no-highlight]
id
[no-highlight[

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

]no-highlight]
="{int32}" name
[no-highlight[

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

]no-highlight]
="{string}" type
[no-highlight[

Тип региона.

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

  • 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 — другой тип населенного пункта.

]no-highlight]
="{enum}" childCount
[no-highlight[

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

]no-highlight]
="{int32}"> <country
[no-highlight[

Страна, к которой относится регион.

Регион

]no-highlight]
>Содержимое объекта</country> </region> <currency
[no-highlight[

Валюта запроса.

]no-highlight]
id
[no-highlight[

Код валюты.

]no-highlight]
="{string}" name
[no-highlight[

Название валюты.

]no-highlight]
="{string}"/> <alternateCurrency
[no-highlight[

Альтернативная валюта запроса.

]no-highlight]
id
[no-highlight[

Код валюты.

]no-highlight]
="{string}" name
[no-highlight[

Название валюты.

]no-highlight]
="{string}"/> <page
[no-highlight[

Информация о параметрах страницы запроса.

]no-highlight]
number
[no-highlight[

Номер страницы.

]no-highlight]
="{int32}" count
[no-highlight[

Размер страницы.

]no-highlight]
="{int32}" total
[no-highlight[

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

]no-highlight]
="{int32}" last
[no-highlight[

Признак последней страницы.

]no-highlight]
="{boolean}" totalItems
[no-highlight[

Количество найденных элементов

]no-highlight]
="{int32}"/> <warnings
[no-highlight[

Список предупреждений, возникших при обработке запроса.

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

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

Тип предупрежедния.

]no-highlight]
="{string}" code
[no-highlight[

Код предупреждения.

]no-highlight]
="{string}" message
[no-highlight[

Сообщение с описанием предупреждения.

]no-highlight]
="{string}"/> ... </warnings> </context> <items
[no-highlight[

Список моделей и/или товарных предложений

Типы:

]no-highlight]
> <item __type="model">Содержимое объекта</item> <item __type="offer">Содержимое объекта</item> ... </items> <categories
[no-highlight[

Список категорий.

Категория в рез-тах поиска

]no-highlight]
> <category>Содержимое объекта</category> ... </categories> <sorts
[no-highlight[

Список доступных сортировок

]no-highlight]
> <sort text
[no-highlight[

Наименование типа сортировки.

]no-highlight]
="{string}" field
[no-highlight[

Тип сортировки.

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

  • RELEVANCY — сортировка по релевантности.

  • PRICE — сортировка по цене.

  • RATING — сортировка по рейтингу.

  • DISTANCE — сортировка по расстоянию до ближайшей точки продаж (значение доступно только при указании местоположения пользователя).

  • POPULARITY — сортировка по популярности.

  • DISCOUNT — сортировка по размеру скидки.

    Ограничение. Для sort=DISCOUNT возможна только сортировка по убыванию (how=DESC).

  • QUALITY — сортировка по рейтингу.

  • OPINIONS — сортировка по количеству отзывов.

  • DATE — сортировка по дате.

  • DELIVERY_TIME — сортировка по времени доставки.

]no-highlight]
="{enum}"> <options
[no-highlight[

Доступные варианты для данного типа сортировки.

]no-highlight]
> <option id
[no-highlight[

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

]no-highlight]
="{string}" how
[no-highlight[

Направление сортировки.

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

  • ASC — по возрастанию;

  • DESC — по убыванию.

]no-highlight]
="{enum}" text
[no-highlight[

Наименование данного варианта сортировки

]no-highlight]
="{string}"/> ... </options> </sort> ... </sorts> </result>

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

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

Enum

Статус обработки запроса.

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

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

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

context context

Object

Контекст обработки запроса.

items items

Object list

Список моделей и/или товарных предложений

Типы:

categories categories

Object list

Список категорий.

Категория в рез-тах поиска

sorts sorts

Object list

Список доступных сортировок

Параметры, вложенные в context.
id id

String

Уникальный идентификатор запроса.

time time

Date

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

link link

String

Ссылка на текущий запрос.

marketUrl marketUrl

String

Ссылка на Яндекс.Маркет

region region

Object

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

currency currency

Object

Валюта запроса.

alternateCurrency alternateCurrency

Object

Альтернативная валюта запроса.

page page

Object

Информация о параметрах страницы запроса.

warnings warnings

Object list

Список предупреждений, возникших при обработке запроса.

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

Параметры, вложенные в context/region.
id id

Int32

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

name name

String

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

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 — другой тип населенного пункта.

childCount childCount

Int32

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

country country

Object

Страна, к которой относится регион.

Регион

Параметры, вложенные в context/currency, context/alternateCurrency.
id id

String

Код валюты.

name name

String

Название валюты.

Параметры, вложенные в context/page.
number number

Int32

Номер страницы.

count count

Int32

Размер страницы.

total total

Int32

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

last last

Boolean

Признак последней страницы.

totalItems totalItems

Int32

Количество найденных элементов

Параметры, вложенные в context/warnings.
type type

String

Тип предупрежедния.

code code

String

Код предупреждения.

message message

String

Сообщение с описанием предупреждения.

Параметры, вложенные в sorts.
text text

String

Наименование типа сортировки.

field field

Enum

Тип сортировки.

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

  • RELEVANCY — сортировка по релевантности.

  • PRICE — сортировка по цене.

  • RATING — сортировка по рейтингу.

  • DISTANCE — сортировка по расстоянию до ближайшей точки продаж (значение доступно только при указании местоположения пользователя).

  • POPULARITY — сортировка по популярности.

  • DISCOUNT — сортировка по размеру скидки.

    Ограничение. Для sort=DISCOUNT возможна только сортировка по убыванию (how=DESC).

  • QUALITY — сортировка по рейтингу.

  • OPINIONS — сортировка по количеству отзывов.

  • DATE — сортировка по дате.

  • DELIVERY_TIME — сортировка по времени доставки.

options options

Object list

Доступные варианты для данного типа сортировки.

Параметры, вложенные в sorts/options.
id id

String

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

how how

Enum

Направление сортировки.

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

  • ASC — по возрастанию;

  • DESC — по убыванию.

text text

String

Наименование данного варианта сортировки

Возможные ошибки

В случае возникновения ошибочной ситуации сервер возвращает HTTP-статус ответа и сообщение об ошибке. Описание ошибок приведено в разделе Сообщения об ошибках.

/{version}/categories/{id}/search Подбор по параметрам в категории Поиск и подбор по параметрам