Выполнение запроса

Чтобы искать в своем интернет-магазине с помощью API, отправьте запрос по адресу https://catalogapi.site.yandex.net/v1.0.

API позволяет:

искать товары по названию или описанию;
сортировать поисковую выдачу по релевантности или цене;
фильтровать выдачу по:
- ценовому диапазону;
- категории товара;
- параметрам товара;
- наличию товара.

В разделе описаны формат запроса к API и возможные ответы на него.

Формат запроса

Формат ответа

Сообщения об ошибках

Формат запроса

Для запроса к поиску используется HTTP-метод GET. Параметры запроса передаются в его URI:

GET /v1.0 ?
 & apikey=<ключ авторизации>
 & searchid=<id поиска>
 & text=<текст поискового запроса>
[& page=<номер страницы>]
[& per_page=<число позиций на странице>]
[& how=<тип сортировки>]
[& price_low=<цена от>]
[& price_high=<цена до>]
[& category_id=<категория для поиска>]
[& r_param_<id>_low=<нижнее значение параметра>]
[& r_param_<id>_high=<верхнее значение параметра>]
[& e_param_<id>=<значение параметра>]
[& available=<true|false>]

Host: https://catalogapi.site.yandex.net

Идентификатор поиска. Чтобы узнать идентификатор, выберите поиск на странице Мои поиски. Идентификатор указан в адресной строке страницы поиска:

https://site.yandex.ru/catalogs/**<идентификатор_поиска>**

Тип данных: целое число.

Значение нечислового параметра с идентификатором <id>. Учитывается только если задана категория для поиска. Параметр считается нечисловым, если выполнено одно из условий:

хотя бы одно значение параметра — строка;
для параметра не указана единица измерений. В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами. Тип данных: строка. Чтобы включить в фильтр несколько значений одного параметра, перечислите их в запросе:

&e_param_<id1>=<значение1>&e_param_<id1>=<значение2>&e_param_<id1>=<значение3>

Параметры запроса

apikey

Ключ для доступа к поиску. О том, как получить ключ см. раздел Доступ к API.

Тип данных: строка.

searchid

https://site.yandex.ru/catalogs/**<идентификатор_поиска>**

Тип данных: целое число.

text

Текст поискового запроса. Текст должен быть оформлен в соответствии с RFC 3986.

Тип данных: строка.

page (необязательный)

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

Тип данных: целое число

per_page (необязательный)

Число позиций на странице выдачи, может принимать значения от 1 до 100. Если параметр не указан, страница содержит не более 10 позиций.

Тип данных: целое число от 1 до 100.

how (необязательный)

Способ сортировки поисковой выдачи:

aprice — сортировка по цене от меньшего к большему;
dprice — сортировка по цене от большего к меньшему;
параметр отсутствует — сортировка по релевантности.

Тип данных: строка.

price_low (необязательный)

Нижняя граница фильтра по цене (в валюте YML-каталога).

Тип данных: число с фиксированной точкой.

price_high (необязательный)

Верхняя граница фильтра по цене (в валюте YML-каталога).

Тип данных: число с фиксированной точкой.

category_id (необязательный)

Идентификатор категории товаров для поиска.

Тип данных: строка.

r_param_<id>_low (необязательный)

Нижняя граница фильтра по числовому параметру с идентификатором <id>. Учитывается только если задана категория для поиска.

Числовыми считаются параметры, для которых выполнены условия:

все значения параметра — числа;
для параметра указана единица измерения.

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

Тип данных: число с фиксированной точкой.

r_param_<id>_high (необязательный)

Верхняя граница фильтра по числовому параметру с идентификатором <id>. Учитывается только если задана категория для поиска.

Числовыми считаются параметры, для которых выполнены условия:

все значения параметра — числа;
для параметра указана единица измерения.

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

Тип данных: число с фиксированной точкой.

e_param_<id> (необязательный)

Значение нечислового параметра с идентификатором <id>. Учитывается только если задана категория для поиска.

Параметр считается нечисловым, если выполнено одно из условий:

хотя бы одно значение параметра — строка;
для параметра не указана единица измерений.

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

Тип данных: строка.

Совет

Чтобы включить в фильтр несколько значений одного параметра, перечислите их в запросе:

&e_param_<id1>=<значение1>&e_param_<id1>=<значение2>&e_param_<id1>=<значение3>

available (необязательный)

Доступность товара:

true — искать только по товарам в наличии;
false или параметр отсутствует — поиск происходит по всем товарам.

Тип данных: логический.

Поисковый запрос по строке «розовый слон»:

HTTP-метод — GET.

Товар только в наличии (available=true).

Ценовой диапазон от 3999.1 до 5000.1 (price_low=3999.1&price_high=5000.1).

Поиск по категории с id=49 (category_id=49).

Фильтр по нечисловому параметру с id=85 (e_param_85=розовый).
https://catalogapi.site.yandex.net/v1.0?apikey=c24a2422-ac83-4c9f-98a6-d500b7d164a2&text=розовый%20слон&searchid=1111111&page=0&available=true&price_low=3999.1&price_high=4000.1&category_id=49&e_param_85=розовый

Формат ответа

В случае успешного выполнения запроса API возвращает ответ с кодом 200. Тело ответа содержит результаты в формате JSON:

{
  "documents" : [
                   {
                     "id" : "<идентификатор_предложения>",
                     "name" : "<название_товара>",
                     "description" : "<описание_товара>",
                     "url" : "<URL_товара>", 
                     "categoryId" : <идентификатор_категории>,
                     "categoryParents" : [<родительская_категория_1>, <родительская_категория_2>, ...],
                     "price" : <цена>,
                     "currencyId" : "<валюта>",
                     "vendor" : "<производитель>",
                     "origSnippet" : "<оригинальное_изображение>",
                     "snippet" : "<изображение>",
                     "mobileSnippet" : "<изображение_для_мобильного>",
                     "parameters" : [
                                      {
                                        "name": "<название_параметра>",
                                        "value":"<значение_параметра>",
                                        "unit":"<единица_измерений>"
                                      },
                                      ...
                                    ],
                     "available" : <true|false>,
                     "oldPrice" : <старая_цена>
                   },
                   ... 
                 ],
  
  "categoryList" : [ 
                     {
                       "id" : <идентификатор_категории>,
                       "value" : "<название_категории>",
                       "parentId" : <родительская_категория>,
                       "found" : <количество_найденных_предложений>
                     },
                     ...
                   ],
  "misspell" : {
                 "reask" : {
                             "rule" : "<тип_ошибки>",
                             "text" : "<исправленный_текст>",
                             "sourceText" : "<исхоный_текст>"
                           },
                 "misspell": {
                             "rule" : "<тип_ошибки>",
                             "text" : "<исправленный_текст>",
                             "sourceText" : "<исхоный_текст>"
                            }
               },
  "page" : <номер_страницы>,
  "perPage" : <позиций_на_странице>,
  "rangeParameters" : [
                        {
                          "param_id" : <идентификатор_параметра>,
                          "name" : "<имя_параметра>",
                          "unit_name" : "<единица_измерений>",
                          "highest" : <максимальное_значение_параметра>,
                          "lowest" : <минимальное_значение_параметра>,
                          "step" : <шаг_изменения_параметра>,
                          "found_min" : <минимальное_найденое_значение>,
                          "found_max" : <максимальное_найденое_значение>
                        },
                        ...
                      ],
  "enumParameters" : [
                       {    
                         "param_id" : <идентификатор_параметра>,
                         "name" : "<имя_параметра>",
                         "unit_name" : null,
                         "values" : {
                                      "items" : [
                                                  {
                                                    "value" : "<значение_параметра>",
                                                    "found" : <число_найденных_предложений>
                                                  },
                                                  ...
                                                ]
                                    }
                       },
                       ...
                     ],
  "docsTotal" : <всего_позиций>
}

Описание

categoryList: Массив категорий товаров. Содержит сведения обо всех категориях товаров и количестве предложений, найденных в каждой категории.
misspell (необязательный): Объект присутствует, если в тексте поискового запроса найдена или исправлена ошибка.
page: Номер страницы поисковой выдачи. Нумерация страниц начинается с нуля.
perPage: Число позиций на странице.
rangeParameters (необязательный): Массив числовых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех числовых параметрах товаров этой категории.
enumParameters (необязательный): Массив нечисловых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех нечисловых параметрах товаров этой категории.
docsTotal: Общее число позиций в поисковой выдаче.

Параметры ответа

documents

Массив с результатами поискового запроса. Состоит из объектов, каждый из которых содержит сведения о найденном товарном предложении. Если ни одного предложения не нашлось, объект documents в ответе отсутствует.

Товарные предложения характеризуются параметрами:

Параметр	Описание	Тип данных
`id`	Идентификатор товарного предложения.	Строка
`name`	Название товара.	Строка
`description`	Описание товара.	Строка
`url`	URL страницы товара.	Строка
`categoryId`	Идентификатор категории, к которой относится товар.	Число
`categoryParents`	Идентификаторы родительских категорий, перечисленные через запятую.	Строка
`price`	Цена товара.	Число
`currencyId`	Идентификатор валюты предложения.	Строка
`vendor`	Название производителя товара.	Строка
`origSnippet`	URL изображения товара из YML-каталога.	Строка
`snippet`	URL изображения товара, оптимизированного для поисковой выдачи.	Строка
`mobileSnippet`	URL уменьшенного изображения товара для отображения на мобильных устройствах.	Строка
`parameters`	Массив объектов с информацией о параметрах товара.	JSON-массив
`available`	Доступность товара. Может принимать значения: `true` — товар есть в наличии; `false` — товар отсутствует.	Логический
`oldPrice`	Старая цена товара.	Число
Поля массива parameters
`name`	Название параметра.	Строка
`value`	Значение параметра.	Строка/число
`unit`	Единица измерений параметра. Необязательное поле.	Строка

categoryList

Массив категорий товаров. Содержит сведения обо всех категориях товаров и количестве предложений, найденных в каждой категории.

Категории характеризуются параметрами:

Параметр	Описание	Тип данных
`id`	Идентификатор категории.	Число
`value`	Название категории	Строка
`parentId`	Идентификатор родительской категории. Если родительских категорий нет, указывается значение `"0"`.	Число
`found`	Количество найденных предложений. Если в категории не нашлось ни одного предложения, указывается значение "`0`".	Число

misspell (необязательный)

Объект присутствует, если в тексте поискового запроса найдена или исправлена ошибка.

Состоит из полей:

Поле	Описание	Тип данных
`reask`	Содержит сведения об автоматически исправленной опечатке. Если в запросе не исправлено ни одной опечатки, поле принимает значение `null`.	JSON-объект
`misspell`	Содержит сведения о найденной, но не исправленной опечатке. Если в запросе не найдено ни одной опечатки, поле принимает значение `null`.	JSON-объект
Поля объекта reask
`rule`	Тип ошибки, найденной в запросе: `Misspell` — опечатка; `KeyboardLayout` — ошибка в раскладке клавиатуры; `Volapyuk` — запрос задан на русском языке в английской транслитерации;	Строка
`text`	Исправленный текст запроса.	Строка
`sourceText`	Исходный текст запроса.	Строка
Поля объекта misspell
`rule`	Тип ошибки, найденной в запросе: `Misspell` — опечатка; `KeyboardLayout` — ошибка в раскладке клавиатуры; `Volapyuk` — запрос задан на русском языке в английской транслитерации;	Строка
`text`	Предложения по исправлению текста запроса.	Строка
`sourceText`	Исходный текст запроса.	Строка

page

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

perPage

Число позиций на странице.

rangeParameters (необязательный)

Массив числовых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех числовых параметрах товаров этой категории.

Числовые параметры характеризуются полями:

Параметр	Описание	Тип данных
`param_id`	Идентификатор параметра.	Число
`name`	Название параметра	Строка
`unit_name`	Единица измерений.	Строка
`highest`	Максимальное значение параметра среди всех предложений в каталоге.	Число
`lowest`	Минимальное значение параметра среди всех предложений в каталоге.	Число
`step`	Шаг изменения параметра.	Число
`found_min`	Минимальное значение параметра среди найденных предложений.	Число
`found_max`	Максимальное значение параметра среди найденных предложений.	Число

enumParameters (необязательный)

Массив нечисловых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех нечисловых параметрах товаров этой категории.

Нечисловые параметры характеризуются полями:

Параметр	Описание	Тип данных
`param_id`	Идентификатор параметра.	Число
`name`	Название параметра	Строка
`unit_name`	Единица измерений.	Строка
`values`	Содержит сведения о возможных значениях параметра.	JSON-массив
Поля массива values
`value`	Значение параметра.	Строка
`found`	Количество найденных предложений. Если с таким значением параметра не нашлось ни одного предложения, указывается значение “0“.	Строка

Внимание

Нечисловые параметры, имеющие больше 1000 значений, не попадают в ответ.

docsTotal

Общее число позиций в поисковой выдаче.

Сообщения об ошибках

Если запрос не был успешно обработан, ответное сообщение содержит информацию о возникших ошибках:

HTTP-код ошибки	Тело сообщения	Описание ошибки
403	`{ "errorCode" : 403, "errorMessage" : "INVALID_KEY" }`	Указан несуществующий ключ доступа, либо ключ доступа заблокирован.
403	`{ "errorCode" : 403, "errorMessage" : "Key <ключ авторизации> not own to search with id <id поиска>" }`	Указанный поиск не соответствует ключу, либо указан несуществующий поиск.
400	`{ "errorCode" : 400, "errorMessage" : "Value '<значение>' for key '<параметр>' is not valid" }`	Один из параметров запроса имеет недопустимое значение или формат данных.
400	`{ "errorCode" : 400, "errorMessage" : "id of search property r_param_<id параметра>_low/high not a number" }` или `{ "errorCode" : 400, "errorMessage" : "id of search property e_param_<id параметра> not a number" }`	Неверно задан идентификатор параметра для фильтра. Идентификатор может быть выражен только числом.

Была ли статья полезна?

Доступ к API