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

Чтобы искать в своем интернет-магазине с помощью 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
Параметры запроса
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
В этой статье: