Выполнение запроса
Чтобы искать в своем интернет-магазине с помощью 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
Ключ для доступа к поиску. О том, как получить ключ см. раздел Доступ к API. Тип данных: строка.
Идентификатор поиска. Чтобы узнать идентификатор, выберите поиск на странице Мои поиски. Идентификатор указан в адресной строке страницы поиска:
https://site.yandex.ru/catalogs/**<идентификатор_поиска>**
Тип данных: целое число.
Текст поискового запроса. Текст должен быть оформлен в соответствии с RFC 3986. Тип данных: строка.
Номер страницы поисковой выдачи. Нумерация страниц начинается с нуля. Тип данных: целое число
Число позиций на странице выдачи, может принимать значения от 1 до 100. Если параметр не указан, страница содержит не более 10 позиций. Тип данных: целое число от 1 до 100.
Способ сортировки поисковой выдачи:
aprice
— сортировка по цене от меньшего к большему;dprice
— сортировка по цене от большего к меньшему;- параметр отсутствует — сортировка по релевантности. Тип данных: строка.
Нижняя граница фильтра по цене (в валюте YML-каталога). Тип данных: число с фиксированной точкой.
Верхняя граница фильтра по цене (в валюте YML-каталога). Тип данных: число с фиксированной точкой.
Идентификатор категории товаров для поиска. Тип данных: строка.
Нижняя граница фильтра по числовому параметру с идентификатором <id>. Учитывается только если задана категория для поиска. Числовыми считаются параметры, для которых выполнены условия:
- все значения параметра — числа;
- для параметра указана единица измерения. В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами. Тип данных: число с фиксированной точкой.
Верхняя граница фильтра по числовому параметру с идентификатором <id>. Учитывается только если задана категория для поиска. Числовыми считаются параметры, для которых выполнены условия:
- все значения параметра — числа;
- для параметра указана единица измерения. В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами. Тип данных: число с фиксированной точкой.
Значение нечислового параметра с идентификатором <id>. Учитывается только если задана категория для поиска. Параметр считается нечисловым, если выполнено одно из условий:
- хотя бы одно значение параметра — строка;
- для параметра не указана единица измерений. В запросе допускается указывать несколько фильтров по параметрам с разными идентификаторами. Тип данных: строка. Чтобы включить в фильтр несколько значений одного параметра, перечислите их в запросе:
&e_param_<id1>=<значение1>&e_param_<id1>=<значение2>&e_param_<id1>=<значение3>
Доступность товара:
true
— искать только по товарам в наличии;false
или параметр отсутствует — поиск происходит по всем товарам. Тип данных: логический.
Параметры запроса
- 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" : <всего_позиций>
}
Массив с результатами поискового запроса. Состоит из объектов, каждый из которых содержит сведения о найденном товарном предложении. Если ни одного предложения не нашлось, объект documents в ответе отсутствует.
Описание Идентификатор товарного предложения. Тип данных Строка
Описание Название товара. Тип данных Строка
Описание Описание товара. Тип данных Строка
Описание URL страницы товара. Тип данных Строка
Описание Идентификатор категории, к которой относится товар. Тип данных Число
Описание Идентификаторы родительских категорий, перечисленные через запятую. Тип данных Строка
Описание Цена товара. Тип данных Число
Описание Идентификатор валюты предложения. Тип данных Строка
Описание Название производителя товара. Тип данных Строка
Описание URL изображения товара из YML-каталога. Тип данных Строка
Описание URL изображения товара, оптимизированного для поисковой выдачи. Тип данных Строка
Описание URL уменьшенного изображения товара для отображения на мобильных устройствах. Тип данных Строка
Описание Массив объектов с информацией о параметрах товара. Тип данных JSON-массив
Описание Название параметра. Тип данных Строка
Описание Значение параметра. Тип данных Строка/число
Описание Единица измерений параметра. Необязательное поле. Тип данных Строка
Описание Доступность товара. Может принимать значения:
- true — товар есть в наличии;
- false — товар отсутствует. Тип данных Логический
Описание Старая цена товара. Тип данных Число
Массив категорий товаров. Содержит сведения обо всех категориях товаров и количестве предложений, найденных в каждой категории.
Описание Идентификатор категории. Тип данных Число
Описание Название категории Тип данных Строка
Описание Идентификатор родительской категории. Если родительских категорий нет, указывается значение "0". Тип данных Число
Описание Количество найденных предложений. Если в категории не нашлось ни одного предложения, указывается значение "0". Тип данных Число
Объект присутствует, если в тексте поискового запроса найдена или исправлена ошибка.
Описание Содержит сведения об автоматически исправленной опечатке. Если в запросе не исправлено ни одной опечатки, поле принимает значение null. Тип данных JSON-объект
Описание Тип ошибки, найденной в запросе:
- Misspell — опечатка;
- KeyboardLayout — ошибка в раскладке клавиатуры;
- Volapyuk — запрос задан на русском языке в английской транслитерации; Тип данных Строка
Описание Исправленный текст запроса. Тип данных Строка
Описание Исходный текст запроса. Тип данных Строка
Описание
Содержит сведения о найденной, но не исправленной опечатке. Если в запросе не найдено ни одной опечатки, поле принимает значение null. Тип данных JSON-объект
Описание Тип ошибки, найденной в запросе:
- Misspell — опечатка;
- KeyboardLayout — ошибка в раскладке клавиатуры;
- Volapyuk — запрос задан на русском языке в английской транслитерации; Тип данных Строка
Описание Предложения по исправлению текста запроса. Тип данных Строка
Описание Исходный текст запроса. Тип данных Строка
Номер страницы поисковой выдачи. Нумерация страниц начинается с нуля.
Число позиций на странице.
Массив числовых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех числовых параметрах товаров этой категории.
Описание Идентификатор параметра. Тип данных Число
Описание Название параметра Тип данных Строка
Описание Единица измерений. Тип данных Строка
Описание Максимальное значение параметра среди всех предложений в каталоге. Тип данных Число
Описание Минимальное значение параметра среди всех предложений в каталоге. Тип данных Число
Описание Шаг изменения параметра. Тип данных Число
Описание Минимальное значение параметра среди найденных предложений. Тип данных Число
Описание Максимальное значение параметра среди найденных предложений. Тип данных Число
Массив нечисловых параметров категории товаров. Присутствует в ответе, если в запросе указана категория для поиска. Содержит сведения обо всех нечисловых параметрах товаров этой категории.
Описание Идентификатор параметра. Тип данных Число
Описание Название параметра Тип данных Строка
Описание Единица измерений. Тип данных Строка
Описание Содержит сведения о возможных значениях параметра. Тип данных JSON-массив
Описание Значение параметра. Тип данных Строка/число
Описание Количество найденных предложений. Если с таким значением параметра не нашлось ни одного предложения, указывается значение “0“. Тип данных Строка
Общее число позиций в поисковой выдаче.
- 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 |
|
Указан несуществующий ключ доступа, либо ключ доступа заблокирован. |
403 |
|
Указанный поиск не соответствует ключу, либо указан несуществующий поиск. |
400 |
|
Один из параметров запроса имеет недопустимое значение или формат данных. |
400 |
или
|
Неверно задан идентификатор параметра для фильтра. Идентификатор может быть выражен только числом. |