> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/site/api/ru/llms.txt # Выполнение запроса Чтобы искать в своем интернет-магазине с помощью API, отправьте запрос по адресу `https://catalogapi.site.yandex.net/v1.0`. API позволяет: - искать товары по названию или описанию; - сортировать поисковую выдачу по релевантности или цене; - фильтровать выдачу по: - ценовому диапазону; - категории товара; - параметрам товара; - наличию товара. В разделе описаны формат запроса к API и возможные ответы на него. [Формат запроса](#concept_) [Формат ответа](#concept_2) [Сообщения об ошибках](#concept_3) ## Формат запроса {#concept_} Для запроса к поиску используется HTTP-метод GET. Параметры запроса передаются в его URI: ```httpget GET /v1.0 ? & [apikey](*apikey)=<ключ авторизации> & [searchid](*searchid)= & [text](*text0)=<текст поискового запроса> [& [page](*page1)=<номер страницы>] [& [per_page](*per_page)=<число позиций на странице>] [& [how](*how)=<тип сортировки>] [& [price_low](*price_low)=<цена от>] [& [price_high](*price_high)=<цена до>] [& [category_id](*category_id)=<категория для поиска>] [& [r_param__low](*r_param_id_low)=<нижнее значение параметра>] [& [r_param__high](*r_param_id_high)=<верхнее значение параметра>] [& [e_param_](*e_param_id)=<значение параметра>] [& [available](*available1)=] Host: https://catalogapi.site.yandex.net ``` [*apikey]: Ключ для доступа к поиску. О том, как получить ключ см. раздел [Доступ к API](https://yandex.ru/dev/site/api/ru/concepts/access.md).   Тип данных: строка. [*searchid]: Идентификатор поиска. Чтобы узнать идентификатор, выберите поиск на странице [Мои поиски](https://site.yandex.ru/searches/). Идентификатор указан в адресной строке страницы поиска:   ```httpget https://site.yandex.ru/catalogs/**<идентификатор_поиска>** ```   Тип данных: целое число. [*text0]: Текст поискового запроса. Текст должен быть оформлен в соответствии с [RFC 3986](https://tools.ietf.org/html/rfc3986).   Тип данных: строка. [*page1]: Номер страницы поисковой выдачи. Нумерация страниц начинается с нуля.   Тип данных: целое число [*per_page]: Число позиций на странице выдачи, может принимать значения от 1 до 100. Если параметр не указан, страница содержит не более 10 позиций.   Тип данных: целое число от 1 до 100. [*how]: Способ сортировки поисковой выдачи:   - `aprice` — сортировка по цене от меньшего к большему; - `dprice` — сортировка по цене от большего к меньшему; - параметр отсутствует — сортировка по релевантности.   Тип данных: строка. [*price_low]: Нижняя граница фильтра по цене (в валюте [YML-каталога](https://www.yandex.ru/support/partnermarket/yml/about-yml.xml#about-yml)).   Тип данных: число с фиксированной точкой. [*price_high]: Верхняя граница фильтра по цене (в валюте YML-каталога).   Тип данных: число с фиксированной точкой. [*category_id]: Идентификатор категории товаров для поиска.   Тип данных: строка. [*r_param_id_low]: Нижняя граница фильтра по числовому параметру с идентификатором \. Учитывается только если задана категория для поиска.   Числовыми считаются параметры, для которых выполнены условия:   - все значения параметра — числа; - для параметра указана единица измерения.   В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами.   Тип данных: число с фиксированной точкой. [*r_param_id_high]: Верхняя граница фильтра по числовому параметру с идентификатором \. Учитывается только если задана категория для поиска.   Числовыми считаются параметры, для которых выполнены условия:   - все значения параметра — числа; - для параметра указана единица измерения.   В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами.   Тип данных: число с фиксированной точкой. [*e_param_id]: Значение нечислового параметра с идентификатором \. Учитывается только если задана категория для поиска.   Параметр считается нечисловым, если выполнено одно из условий:   - хотя бы одно значение параметра — строка; - для параметра не указана единица измерений.   В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами.   Тип данных: строка.   Чтобы включить в фильтр несколько значений одного параметра, перечислите их в запросе:   ```httpget &e_param_=<значение1>&e_param_=<значение2>&e_param_=<значение3> ``` [*available1]: Доступность товара:   - `true` — искать только по товарам в наличии; - `false` или параметр отсутствует — поиск происходит по всем товарам.   Тип данных: логический. {% cut "Параметры запроса" %} apikey : Ключ для доступа к поиску. О том, как получить ключ см. раздел [Доступ к API](https://yandex.ru/dev/site/api/ru/concepts/access.md). Тип данных: строка. searchid : Идентификатор поиска. Чтобы узнать идентификатор, выберите поиск на странице [Мои поиски](https://site.yandex.ru/searches/). Идентификатор указан в адресной строке страницы поиска: ```httpget https://site.yandex.ru/catalogs/**<идентификатор_поиска>** ``` Тип данных: целое число. text : Текст поискового запроса. Текст должен быть оформлен в соответствии с [RFC 3986](https://tools.ietf.org/html/rfc3986). Тип данных: строка. page (необязательный) : Номер страницы поисковой выдачи. Нумерация страниц начинается с нуля. Тип данных: целое число per_page (необязательный) : Число позиций на странице выдачи, может принимать значения от 1 до 100. Если параметр не указан, страница содержит не более 10 позиций. Тип данных: целое число от 1 до 100. how (необязательный) : Способ сортировки поисковой выдачи: - `aprice` — сортировка по цене от меньшего к большему; - `dprice` — сортировка по цене от большего к меньшему; - параметр отсутствует — сортировка по релевантности. Тип данных: строка. price_low (необязательный) : Нижняя граница фильтра по цене (в валюте [YML-каталога](https://www.yandex.ru/support/partnermarket/yml/about-yml.xml#about-yml)). Тип данных: число с фиксированной точкой. price_high (необязательный) : Верхняя граница фильтра по цене (в валюте [YML-каталога](https://www.yandex.ru/support/partnermarket/yml/about-yml.xml#about-yml)). Тип данных: число с фиксированной точкой. category_id (необязательный) : Идентификатор категории товаров для поиска. Тип данных: строка. r_param_\_low (необязательный) : Нижняя граница фильтра по числовому параметру с идентификатором \. Учитывается только если задана категория для поиска. Числовыми считаются параметры, для которых выполнены условия: - все значения параметра — числа; - для параметра указана единица измерения. В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами. Тип данных: число с фиксированной точкой. r_param_\_high (необязательный) : Верхняя граница фильтра по числовому параметру с идентификатором \. Учитывается только если задана категория для поиска. Числовыми считаются параметры, для которых выполнены условия: - все значения параметра — числа; - для параметра указана единица измерения. В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами. Тип данных: число с фиксированной точкой. e_param_\ (необязательный) : Значение нечислового параметра с идентификатором \. Учитывается только если задана категория для поиска. Параметр считается нечисловым, если выполнено одно из условий: - хотя бы одно значение параметра — строка; - для параметра не указана единица измерений. В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами. Тип данных: строка. {% note tip %} Чтобы включить в фильтр несколько значений одного параметра, перечислите их в запросе: ```httpget &e_param_=<значение1>&e_param_=<значение2>&e_param_=<значение3> ``` {% endnote %} available (необязательный) : Доступность товара: - `true` — искать только по товарам в наличии; - `false` или параметр отсутствует — поиск происходит по всем товарам. Тип данных: логический. {% endcut %} > Поисковый запрос по строке «розовый слон»: > > - 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=розовый > ``` ## Формат ответа {#concept_2} В случае успешного выполнения запроса API возвращает ответ с кодом 200. Тело ответа содержит результаты в формате JSON: ```javascript { "[documents](*documents)" : [ { "[id](*id1)" : "<идентификатор_предложения>", "[name](*name1)" : "<название_товара>", "[description](*description)" : "<описание_товара>", "[url](*url)" : "", "[categoryId](*categoryId)" : <идентификатор_категории>, "[categoryParents](*categoryParents)" : [<родительская_категория_1>, <родительская_категория_2>, ...], "[price](*price)" : <цена>, "[currencyId](*currencyId)" : "<валюта>", "[vendor](*vendor)" : "<производитель>", "[origSnippet](*origSnippet)" : "<оригинальное_изображение>", "[snippet](*snippet)" : "<изображение>", "[mobileSnippet](*mobileSnippet)" : "<изображение_для_мобильного>", "[parameters](*parameters)" : [ { "[name](*name2)": "<название_параметра>", "[value](*value1)":"<значение_параметра>", "[unit](*unit)":"<единица_измерений>" }, ... ], "[available](*available2)" : , "[oldPrice](*oldPrice)" : <старая_цена> }, ... ], "[categoryList](*categoryList)" : [ { "[id](*id2)" : <идентификатор_категории>, "[value](*value2)" : "<название_категории>", "[parentId](*parentId)" : <родительская_категория>, "[found](*found1)" : <количество_найденных_предложений> }, ... ], "[misspell](*misspell1)" : { "[reask](*reask)" : { "[rule](*rule1)" : "<тип_ошибки>", "[text](*text1)" : "<исправленный_текст>", "[sourceText](*sourceText1)" : "<исхоный_текст>" }, "[misspell](*misspell2)": { "[rule](*rule2)" : "<тип_ошибки>", "[text](*text2)" : "<исправленный_текст>", "[sourceText](*sourceText2)" : "<исхоный_текст>" } }, "[page](*page2)" : <номер_страницы>, "[perPage](*perPage)" : <позиций_на_странице>, "[rangeParameters](*rangeParameters)" : [ { "[param_id](*param_id1)" : <идентификатор_параметра>, "[name](*name3)" : "<имя_параметра>", "[unit_name](*unit_name1)" : "<единица_измерений>", "[highest](*highest)" : <максимальное_значение_параметра>, "[lowest](*lowest)" : <минимальное_значение_параметра>, "[step](*step)" : <шаг_изменения_параметра>, "[found_min](*found_min)" : <минимальное_найденое_значение>, "[found_max](*found_max)" : <максимальное_найденое_значение> }, ... ], "[enumParameters](*enumParameters)" : [ { "[param_id](*param_id2)" : <идентификатор_параметра>, "[name](*name4)" : "<имя_параметра>", "[unit_name](*unit_name2)" : null, "[values](*values)" : { "items" : [ { "[value](*value3)" : "<значение_параметра>", "[found](*found2)" : <число_найденных_предложений> }, ... ] } }, ... ], "[docsTotal](*docsTotal)" : <всего_позиций> } ``` [*documents]: Массив с результатами поискового запроса. Состоит из объектов, каждый из которых содержит сведения о найденном товарном предложении. Если ни одного предложения не нашлось, объект _documents_ в ответе отсутствует. [*id1]: **Описание**   Идентификатор товарного предложения.   **Тип данных**   Строка [*name1]: **Описание**   Название товара.   **Тип данных**   Строка [*description]: **Описание**   Описание товара.   **Тип данных**   Строка [*url]: **Описание**   URL страницы товара.   **Тип данных**   Строка [*categoryId]: **Описание**   Идентификатор категории, к которой относится товар.   **Тип данных**   Число [*categoryParents]: **Описание**   Идентификаторы родительских категорий, перечисленные через запятую.   **Тип данных**   Строка [*price]: **Описание**   Цена товара.   **Тип данных**   Число [*currencyId]: **Описание**   Идентификатор валюты предложения.   **Тип данных**   Строка [*vendor]: **Описание**   Название производителя товара.   **Тип данных**   Строка [*origSnippet]: **Описание**   URL изображения товара из YML-каталога.   **Тип данных**   Строка [*snippet]: **Описание**   URL изображения товара, оптимизированного для поисковой выдачи.   **Тип данных**   Строка [*mobileSnippet]: **Описание**   URL уменьшенного изображения товара для отображения на мобильных устройствах.   **Тип данных**   Строка [*parameters]: **Описание**   Массив объектов с информацией о параметрах товара.   **Тип данных**   JSON-массив [*name2]: **Описание**   Название параметра.   **Тип данных**   Строка [*value1]: **Описание**   Значение параметра.   **Тип данных**   Строка/число [*unit]: **Описание**   Единица измерений параметра. Необязательное поле.   **Тип данных**   Строка [*available2]: **Описание**   Доступность товара. Может принимать значения:   - true — товар есть в наличии; - false — товар отсутствует.   **Тип данных**   Логический [*oldPrice]: **Описание**   Старая цена товара.   **Тип данных**   Число [*categoryList]: Массив категорий товаров. Содержит сведения обо всех категориях товаров и количестве предложений, найденных в каждой категории. [*id2]: **Описание**   Идентификатор категории.   **Тип данных**   Число [*value2]: **Описание**   Название категории   **Тип данных**   Строка [*parentId]: **Описание**   Идентификатор родительской категории. Если родительских категорий нет, указывается значение "0".   **Тип данных**   Число [*found1]: **Описание**   Количество найденных предложений. Если в категории не нашлось ни одного предложения, указывается значение "0".   **Тип данных**   Число [*misspell1]: Объект присутствует, если в тексте поискового запроса найдена или исправлена ошибка. [*reask]: **Описание**   Содержит сведения об автоматически исправленной опечатке.   Если в запросе не исправлено ни одной опечатки, поле принимает значение null.   **Тип данных**   JSON-объект [*rule1]: **Описание**   Тип ошибки, найденной в запросе:   - Misspell — опечатка; - KeyboardLayout — ошибка в раскладке клавиатуры; - Volapyuk — запрос задан на русском языке в английской транслитерации;     **Тип данных**   Строка [*text1]: **Описание**   Исправленный текст запроса.   **Тип данных**   Строка [*sourceText1]: **Описание**   Исходный текст запроса.   **Тип данных**   Строка **Описание**   [*misspell2]: Содержит сведения о найденной, но не исправленной опечатке.   Если в запросе не найдено ни одной опечатки, поле принимает значение null.   **Тип данных**   JSON-объект [*rule2]: **Описание**   Тип ошибки, найденной в запросе:   - Misspell — опечатка; - KeyboardLayout — ошибка в раскладке клавиатуры; - Volapyuk — запрос задан на русском языке в английской транслитерации;   **Тип данных**   Строка [*text2]: **Описание**   Предложения по исправлению текста запроса.   **Тип данных**   Строка [*sourceText2]: **Описание**   Исходный текст запроса.   **Тип данных**   Строка [*page2]: Номер страницы поисковой выдачи. Нумерация страниц начинается с нуля. [*perPage]: Число позиций на странице. [*rangeParameters]: Массив числовых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех числовых параметрах товаров этой категории. [*param_id1]: **Описание**   Идентификатор параметра.   **Тип данных**   Число [*name3]: **Описание**   Название параметра   **Тип данных**   Строка [*unit_name1]: **Описание**   Единица измерений.   **Тип данных**   Строка [*highest]: **Описание**   Максимальное значение параметра среди всех предложений в каталоге.   **Тип данных**   Число [*lowest]: **Описание**   Минимальное значение параметра среди всех предложений в каталоге.   **Тип данных**   Число [*step]: **Описание**   Шаг изменения параметра.   **Тип данных**   Число [*found_min]: **Описание**   Минимальное значение параметра среди найденных предложений.   **Тип данных**   Число [*found_max]: **Описание**   Максимальное значение параметра среди найденных предложений.   **Тип данных**   Число [*enumParameters]: Массив нечисловых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех нечисловых параметрах товаров этой категории. [*param_id2]: **Описание**   Идентификатор параметра.   **Тип данных**   Число [*name4]: **Описание**   Название параметра   **Тип данных**   Строка [*unit_name2]: **Описание**   Единица измерений.   **Тип данных**   Строка [*values]: **Описание**   Содержит сведения о возможных значениях параметра.   **Тип данных**   JSON-массив [*value3]: **Описание**   Значение параметра.   **Тип данных**   Строка/число [*found2]: **Описание**   Количество найденных предложений. Если с таким значением параметра не нашлось ни одного предложения, указывается значение “0“.   **Тип данных**   Строка [*docsTotal]: Общее число позиций в поисковой выдаче. categoryList : Массив категорий товаров. Содержит сведения обо всех категориях товаров и количестве предложений, найденных в каждой категории. misspell (необязательный) : Объект присутствует, если в тексте поискового запроса найдена или исправлена ошибка. page : Номер страницы поисковой выдачи. Нумерация страниц начинается с нуля. perPage : Число позиций на странице. rangeParameters (необязательный) : Массив числовых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех числовых параметрах товаров этой категории. enumParameters (необязательный) : Массив нечисловых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех нечисловых параметрах товаров этой категории. docsTotal : Общее число позиций в поисковой выдаче. {% cut "Параметры ответа" %} 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“. | Строка |# {% note alert %} Нечисловые параметры, имеющие больше 1000 значений, не попадают в ответ. {% endnote %} docsTotal : Общее число позиций в поисковой выдаче. {% endcut %} ## Сообщения об ошибках {#concept_3} Если запрос не был успешно обработан, ответное сообщение содержит информацию о возникших ошибках: #| ||**HTTP-код ошибки** | **Тело сообщения** | **Описание ошибки**|| ||403 | ``` { "errorCode" : 403, "errorMessage" : "INVALID_KEY" } ``` | Указан несуществующий ключ доступа, либо ключ доступа заблокирован.|| ||403 | ``` { "errorCode" : 403, "errorMessage" : "Key <ключ авторизации> not own to search with id " } ``` | Указанный поиск не соответствует ключу, либо указан несуществующий поиск.|| ||400 | ``` { "errorCode" : 400, "errorMessage" : "Value '<значение>' for key '<параметр>' is not valid" } ``` | Один из параметров запроса имеет недопустимое значение или формат данных.|| ||400 | ``` { "errorCode" : 400, "errorMessage" : "id of search property r_param__low/high not a number" } ``` или ``` { "errorCode" : 400, "errorMessage" : "id of search property e_param_ not a number" } ``` | Неверно задан идентификатор параметра для фильтра. Идентификатор может быть выражен только числом.|| |#