Оглавление

Features

Please read information below to find out how goods search is performed and what search settings can be done.

Товарный провайдер

Товарный провайдер — это сервис (или площадка) для торговли. Именно от товарного провайдера поступает информация о товарах (названия, настройки, конфигурации и тд) и товарных категориях в OT API и потом, с помощью ключа, транслируется на сайт владельца ключа.

На данный момент доступны для подключения Taobao (включая Tmall), Yahoo.co.jp, 1688.com .

Получить список доступных провайдеров и некоторую информацию о них можно методом GetProviderInfoList.

Таобао и Tmall

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

Название	Идентификатор	Описание
Расширенный поиск	Extended	Поиск по всему каталогу Таобао, используя специальные алгоритмы OT
Tmall поиск	Official	Поиск по товарам Tmall, используя официальное API

Yahoo.co.jp

Содержит в себе 2 провайдера:

Обычная продажа товаров.
Аукционные товары.

Каждый провайдер имеет один поиск.

Свой каталог

С помощью дополнительного модуля «Товары на складе» появится провайдер «Склад», для которого можно создать и заполнить свой каталог товаров.

Подробнее о модуле и его подключении: http://key.otcommerce.com/ru/service-payments-rates

Способы и условия поиска

У каждого товарного провайдера есть свой набор условий поиска. Этот набор можно варьировать под цели сайта. Получить список доступных способов поиска и полную информацию о том, что они поддерживают, можно методом GetProviderSearchMethodInfoList.

Сам поиск можно выполнить двумя методами: SearchItemsFrame и BatchSearchItemsFrame. По работе они полностью идентичны, только с помощью второго метода можно получить различную дополнительную информацию сразу за один запрос, помимо самого поиска. Возможная дополнительная информация будет описана далее.

Условия самого поиска также идентичны, передаются в параметр xmlParameters, и представлены структурой.OtapiSearchItemsParameters. Как и все структурные параметры, он имеет формат xml, примеры будут описаны далее.

В следующей таблице представлено сравнительное описание условий поиска, как они представлены в структуре параметров, и как они представлены в описании способов поиска.

Trade provider

Trade provider is a service (or marketplace) for trading. Information about goods (titles, settings, configuration, etc.) and categories is sent to OT API from trade provider and then is broadcasted to website via OT API Key.

Check available trade providers.

Use GetProviderInfoList method to get list of available providers and information about them.

Own catalog

"Warehouse" provider will be added with additional Goods from Stock Module. You can use it to create your own catalog and add any goods (either from available providers or your own).

Search options and conditions

Each provider has its own set of search conditions. It can be varied depending on website goals. Use GetProviderSearchMethodInfoList method to get list of available search options and information what they support.

Search can be done by two methods: SearchItemsFrame and BatchSearchItemsFrame. They are completely identical. Difference is that BatchSearchItemsFrame allows to get additional information right per one request besides search itself. Possible additional information will be described below.

Search conditions are also identical. They are sent into xmlParameters and presented by structure SearchItemsParameters (this structure can be found, for example, in BatchSearchItemsFrame under "xmlParameters" field by clicking on "Structure"). It has xml format (like other structure parameters). xmlParameters is obligatory as it defines what we are looking for. Examples will be described below.

What is called search conditions

The main search criteria: search phrase, category, vendor, brand.
Additional search criteria: filters by characteristics, novelty of goods, and another different product’s parameters.
Sorting of search results.

From information about search methods you can get information what is available from these, and what variants are available.

Getting information about search methods

Using GetProviderSearchMethodInfoList allows get all possible methods of search.
GetAvailableProviderSearchMethodInfoListForSearchParameters method allows get relevant methods of search by specified parameters.
If to specify additional block AvailableSearchMethods, you can get information about search methods immediately with products searching.

In the following table you can see what can be known in information about search method and what search conditions it affects. For example, for search condition OrderBy (items sorting) can be found possible values from AvailableSorts field. In information about search method these parameters are in the table in one line.

Comparison of search conditions and capabilities

The following table provides a comparative description of search methods as they appear in parameters structure and how they are presented in search methods description.

BrandСостояние товара (новый, б/у, неиспользованыйУправление выдачей

Parameter	Search methods			Search method information
Parameter	Parameter name	Value example	Parameter desription	Parameter title	Value example	Parameter desription
Provider	Provider	Taobao	Provider will be defined by other conditions (for example, categories) if provider was not explicitly specified in search methods. Search will be done by default provider if none of conditions defines provider. Search is impossible and will give an error if different search methods lead to different providers.	Provider	Taobao	Provider ID
Search method	SearchMethod	Official	Default search method defined in settings is used if another one is not set.	SearchMethod	Official	Search method title
				DisplayName	Branded goods (Tmall)	Displayed search method title (in necessary language)
				Flags		List of search method features
Goods quantity limitations	UseOptimalFrameSize	true/false	Feature of using optimal frame size insted of sent one. frameSize parameter is ignored and OptimalFrameSize parameter will be used from chosen search method if this condition was sent in true value.
				OptimalFrameSize	40	Optimal number of requested goods (page size). Maximum possible search speed is available if such size of pages is used because it meets size of provider's pages.
				MaximumFrameSize	200	Maximum quantity of pages received for 1 query. It can work much faster when using optimum number.
				MaximumItemsCount	4000	Number of goods received by the same search methods. Change and define search conditions to receive more goods.
Goods order	OrderBy	Price:Asc	Default sorting set in settings will be used if value is not set or is not included into available.	AvailableSorts		List of available sorting in search method.
Category	CategoryId	16	Category ID for search.
Item title	ItemTitle	dress	Search box for item title. If only item ID (item code) or link to provider's website page is indicated then only this item will be found and shown in search results (or empty if there is no such product).
Item title	LanguageOfQuery	ru	Search box language by item title. It is equal to language of goods query if not set. Autotranslation to provider language is done if it is not equal to provider language.
Vendor	VendorId		Vendor ID	Vendor	true/false	If search by vendor is supported.
Vendor	VendorName		Vendor name	Vendor	true/false	If search by vendor is supported.
Vendor area	VendorAreaId		Vendor area ID	VendorLocation	true/false	If search method supports vendor area.
Vendor rating				VendorRatingRange	true/false	If search method supports filter by vendor rating.
	MinVendorRating	5	Minimum value of vendor rating	MinVendorRating	1	Minimum value of vendor rating.
	MaxVendorRating	15	Maximum value of vendor rating	MaxVendorRating	20	Maximum value of vendor rating. NOTE! Maximum value of vendor rating varies from trade provider to trade provider. You can find it in provider's available search methods.
Brand	BrandId		Brand ID	Brand	true/false	If search method supports brands.
Brand	BrandPropertyValueId		Vrand Value ID (old parameter, use BrandId)	Brand	true/false	If search method supports brands.
Price	MinPrice	10	Minimum price	PriceRange	true/false	If search method supports filter by item price.
	MaxPrice	1000	Maximum price
	CurrencyCode	CNY	Currency code for price range First showcase currency is default one. It is converted by reverse charge and courses into provider currency for search.
Sales volume	MinVolume	100	Minimum sales volume	VolumeRange	true/false	If search method supports filter by sales volume.
	MaxVolume	500	Maximum sales volume	VolumeRange	true/false	If search method supports filter by sales volume.
	Параметр	Условия поиска			Информация о способе поиска
Название параметра	Параметр	Пример значения	Описание параметра	Название параметра	Пример значения	Описание параметра
Провайдер	Provider	Taobao	Если в условиях поиска не указан провайдер явно, он будет определен по другим условиям (например, категории). Если ни одно условие не определяет провайдера, поиск будет произведен в провайдере по умолчанию. Если разные условия поиска ведут к различным провайдерам, то такой поиск невозможен и приведет к ошибке.	Provider	Taobao	Идентификатор провайдера
Способ поиска	SearchMethod	Official	Если не указано, используется определенный в настройках способ поиска по умолчанию.	SearchMethod	Official	Название способа поиска
				DisplayName	Фирменные товары (Tmall)	Отображаемое название способа поиска (на нужном языке)
				Flags		Список особенностей способа поиска
Ограничения на число товаров	UseOptimalFrameSize	true/false	Признак использования оптимального размера фрейма вместо переданного. Если данное условие передано в значении true, то параметр frameSize игнорируется, и будет использовано OptimalFrameSize из выбранного способа поиска.
				OptimalFrameSize	40	Оптимальное число запрашиваемых товаров (размер страницы). Если использовать страницы данного размера, это обеспечивает максимальную возможную скорость работы поиска, т.к. оно соответствует размерам страниц у провайдера.
				MaximumFrameSize	200	Максимальное число товаров, которое можно получить за 1 запрос. Может работать значительно медленнее, чем при использовании оптимального числа.
				MaximumItemsCount	4000	Число товаров, до которого в принципе можно получить по одним и тем же условиям поиска. Чтобы получать больше товаров, надо менять и уточнять условия поиска.
Сортировка товаров	OrderBy	Price:Asc	Если не указано, или указанное значение не входит в число допустимых, будет использована определенная в настройках сортировка по умолчанию.	AvailableSorts		Список допустимых сортировок в способе поиска.
Категория	CategoryId	16	Идентификатор категории, в которой искать товары.
Название товара	ItemTitle	платье	Поисковая строка по названию товара. Если в поисковой строке указаны только идентификатор (артикул) товара или ссылка на страницу на сайте провайдера, то будет найден и выдан именно этот единственный товар (или пусто, если таковой товар отсутствует).
Название товара	LanguageOfQuery	ru	Язык поисковой строки по названию товара. Если не указан, считается равным языку выдачи товаров. Если не равен языку провайдера, то производится автоперевод на язык провайдера.
Продавец	VendorId		Идентификатор продавца	Vendor	true/false	Поддерживается ли поиск по продавцу
Продавец	VendorName		Имя продавца	Vendor	true/false	Поддерживается ли поиск по продавцу
Местонахождение продавца	VendorAreaId		Идентификатор местонахождения продавца (зоны)	VendorLocation	true/false	Поддерживает ли способ поиска местонахождение продавца
Рейтинг продавца				VendorRatingRange	true/false	Поддерживает ли способ поиска фильтр по рейтингу продавца
	MinVendorRating	5	Минимальное значение рейтинга продавца	MinVendorRating	1	Минимальное значение рейтинга продавца
	MaxVendorRating	15	Максимальное значение рейтинга продавца	MaxVendorRating	20	Максимальное значение рейтинга продавца
Бренд	BrandId		Идентификатор искомой торговой марки	true/false	Поддерживает ли способ поиска бренды
Бренд	BrandPropertyValueId		Идентификатор значения искомой торговой марки (устаревший параметр, используйте BrandId)	true/false	Поддерживает ли способ поиска бренды
Цена	MinPrice	10	Минимальная цена	PriceRange	true/false	Поддерживает ли способ поиска фильтр по цене товара
	MaxPrice	1000	Максимальная цена
	CurrencyCode	CNY	Код валюты, в которой указан диапазон цен. По умолчанию считается первая витринная валюта. Для поиска конвертируется по обратным правилам наценок и курсов в валюту провайдера.
Объем продаж	MinVolume	100	Минимальный объем продаж	VolumeRange	true/false	Поддерживает ли способ поиска фильтр по объему продаж
	MaxVolume	500	Максимальный объем продаж	VolumeRange	true/false	Поддерживает ли способ поиска фильтр по объему продаж

			VolumeRangeLogic	None / Range / OnlyMin / OnlyMax	Логика работы условий по объему продаж: диапазон, только минимум, только максимум.	The logic of conditions by sales volume: range, only minimum, only maximum.
Item status (new, second-hand, unused	)	StuffStatus	New / Unused / Second	Состояние товараItem status	StuffStatus	true/false	Поддерживает ли способ поиска фильтр по состоянию товара	If search method supports filter by item status.
Item configurations (color, model, etc.)	Configurators		List of search features provided by structure	Характеристики товара (цвет, модель и тд)	Configurators		Список поисковых свойств, представленных структурой.	Configurators	true/false	Поддерживает ли способ поиска характеристики товараIf search method supports item features.
Item configurations (color, model, etc.)	Configurators		List of search features provided by structure	Характеристики товара (цвет, модель и тд)	Configurators		Список поисковых свойств, представленных структурой.	MultipleConfiguratorLogic	None / All / And	Логика работы способа поиска по нескольким значениям одной характеристики. Использование в поиске нескольких значений одной характеристики. (например, можно вывести только красное, красное И зеленое, красное ИЛИ зеленое)
Особенности товара	Features		Список искомых фич товара	Features		Список специальных фильтров, поддерживаемых способом поиска
The logic of search method by several values of one feature. Use in search of several values of one feature (for example, it is possible to output only red AND green or red OR green).
Item features	Features		List of item features.	Features		List of special filters supported by search method.
Search by photo	ImageUrl		Address of the image to search for goods	Module	Image	Photo search parameters are allowed only in the search mode, in which the Module property is equal to Image
Search by photo	ImageFileId		Image File ID for Product Search Used if the image you searched for was first uploaded via OTAPI.	Module	Image
Output mode		OutputMode	Full / TotalCount / Provider	Режим выдачи результатов поиска. По умолчанию делается обычный поиск, с выдачей товаров и всего сопутствующего. Другие варианты: TotalCount — Выдача только общего количества товаров, без самих данных о товарах. Тем самым можно получить общее количество по данным условиям поиска, и не тратить время на обработку самих товаров. Provider — Выдача только провайдера и способа поиска, которыми бы производился поиск, без самого поиска. Провайдер и способ поиска определяются на основе всех переданных условий поиска и различных настроек.				Search results output mode. Usual search with goods output and all related information is done. Other variants: TotalCount — output of only total number of goods without information about goods. It is thus possible to get total number without wasting time for processing goods themselves. Provider — output of only provider and search method without search itself. Provider and search method are defined on the basis of all search conditions and different settings.
Output mode		CategoryMode	Nothing / External / InternalLeaf / CurrentLevel	Режим выдачи категорий в результатах поиска. В результатах поиска помимо товаров есть еще, хоть и не всегда, список категорий, в которых находятся найденные товары. Обычно они называются уточняющими категориями. Есть несколько вариантов обработки и выдачи данного списка. Nothing — Отсутствие выдачи категорий (если они не нужны) External — Выдача внешних категорий как есть, без приведения к внутренним InternalLeaf — Приведение внешних категорий к внутренним конечным (в любом месте каталога) CurrentLevel — Приведение внешних категорий к внутренним категориям текущего уровня. Если поиск не по категории, то к корневым. Если поиск по категории, то к тем что внутри неё. Тем самым уточняющие категории никогда не выходят за рамки текущего уровня просмотра каталога.
IsClearItemTitles	true/false	Признак очистки заголовков товаров. По умолчанию true, то есть поиск выдает только оригинальные не-переведенные названия товаров, т.к. в большинстве случаев названия не показываются в списке товаров, то данное поведение сильно экономит ресурсы транслятора и немного ускоряет получение результатов поиска. При значении false, в каждом товаре также выдается и переведенное название.
Устаревшие условия	IsOriginal	true/false	Признак выбора только оригинальных товаров
Устаревшие условия	IsTmall	true/false	Признак выбора только товаров из Tmall

Примеры параметров с условиями поиска и запросов поиска

Пример	Значение xmlParameters	Тестовый запрос

Описание результатов поиска

Результаты поиска представлены структурой OtapiItemSearchResult, ниже описание её полей.

Параметр	Описание
Items	Список найденных товаров с указанием полного числа товаров
Categories	Список категорий, в которых есть искомые товары (уточняющие товары)
Brands	Список брендов, в которых встречаются товары (уточняющие бренды)
TranslatedItemTitle	Текст, по которому реально искались товары (переведенный на язык провайдера)
Provider	Товарный провайдер, в котором был произведен поиск
SearchMethod	Способ поиска, которым был произведен поиск
CurrentSort	Реальная текущая сортировка
CurrentFrameSize	Реальный текущий размер фрейма (страницы)
MaximumPageCount	Максимальное число страниц в поиске
IsFoundByItemId	Если true, то в результатах поиска содержится 1 товар, который был найден по артикулу или ссылке

Дополнительные блоки информации в BatchSearchItemsFrame

Используя метод BatchSearchItemsFrame, можно получить дополнительную информацию за тот же один запрос к OTAPI. Список дополнительных блоков передается в параметре blockList, через запятую. Результатом является BatchItemSearchResult, который включает в себя обычный OtapiItemSearchResult, а также все свойства для дополнительной информации.

Categories in search results output mode.

There is categories list (not always) besides goods in search results. These categories include found goods. They are usually called clarifying categories. There are several variants of processing and output:

Nothing — no categories output (if they are unnecessary)
External — output of external categories as they are without cast to internal
InternalLeaf — external categories cast to internal final categories (in any place of catalog)
CurrentLevel — external categories cast to internal categories of current level or to root categories (if search was not by category) or to those inside category (if search was by category). Thus, clarifying categories never go beyond current level of directory view.

Old conditions

IsTmall

true/false

Feature of only Tmall goods choice.

Examples of parameters with search conditions and search requests

Example

xmlParameters value

Test request

Comment

20 items of Taobao provider

Блок кода

language	xml
firstline	1
linenumbers	true
collapse	true

<SearchItemsParameters>
<Provider>Taobao</Provider>
<CategoryId>0</CategoryId>
</SearchItemsParameters>

Parameter	Description
Items	List of found goods with full number of goods
Categories	List of categories containing searched goods (clarifying goods)
Brands	List of brands containing goods (clarifying brands)
TranslatedItemTitle	Text by which goods were really searched (translated to provider language)
Provider	Provider in which search was done
SearchMethod	Search method used for search
CurrentSort	Real current sorting
CurrentFrameSize	Real current frame size (page)
MaximumPageCount	Maximum number of pages in search
IsFoundByItemId	If true, then search results contain 1 product found by code or link

Block name	Description
SubCategories	get all subcategories if search by category
SearchProperties	get filters by characteristics/properties
RootPath	get path to root if search by category
Vendor	get information on seller if search by seller
Brand	get information on brand if search by brand
Category	get information on category of search by category
HintCategories	get appropriate categories for title if search by text
AvailableSearchMethods	get list of appropriate matching data for search methods parameters and all information on them
Название блока	Описание

Дерево страниц

История страницы

Сравнение версий

Старая версия 3

Новая версия Текущий

Ключ