Product Search
The Product Search web service returns product offerings for a selected keyword, category and/or merchant. This service is the key component in our shopping web services and it will provide you with a powerful search engine that allow your users to quickly search and browse millions of product offerings from our partners.
- Name: Product Search
- Version: 3.0
- Path: /V3/productSearch
- Schemas: productSearch.xsd, common.xsd
- Markets: All markets
Please note that productSearch is limited to 500 results in a maximum block of 100. You can offset the result set by declaring a value for the ‘start’ parameter.
If you require a larger result set you should consider using Kelkoo Feeds.
Request Parameters
The Product Search web service supports the folowing request parameters:
| Name | Type | Summary |
|---|---|---|
| query | string | The keywords to search for. Ex. Sony. the query parameter is optional when using category or refinements. |
| category | integer (optional) | The category to search in. It is the category ID. |
| merchantId | integer (optional) | Limit the search to a specific merchant. Merchant ID’s can be obtained from Offer Elements in Product Search and Catalog Listing web services. |
| classification | integer (optional) | Limit the search to a specific product classification. Classification values can be obtained from classification refinement values. |
| max_refines | integer (optional) 0-2000 |
Specifies the maximum number of refinement values to be returned for each refinement key. (Can only be used when specifying category) |
| refinement | string (optional) | The refinement value(s) to use in this request. Based on product search behavior. Can only be used when specifying category. Can only be used if enabled in the client profile. Several values can be passed by using the following syntax: “value1,value2,value3”. |
| sort | string (optional) | Sort the results by:
|
| start | integer (optional) default 1 |
The starting result position to return. |
| results | integer (optional) | The number of offers to return |
| show_products | bool (optional) 0 or 1 |
When set to 1, the response will return products.When set to 0, the response does not return any products |
| show_refinements | bool (optional) 0 or 1 |
When set to 1, the response will return refinements if they are available.When set to 0, the response will not return refinements. |
| show_subcategories | bool (optional) 0 or 1 |
When set to 1, the response will return any available subcategories.When set to 0, the response does not return subcategories. |
| logicalType | AND or OR | for a query with several terms (term 1; term 2), the results return can be :
|
| ean | String (optional) | Limit the search to a specific EAN product. |
| brandName | String (optional) | Limit the search to product with written brand name |
| offerId | String (optional) | Id of wanted offer to limit refine search on specific offer |
| productId | String (optional) | Product Id of wanted product to limit offers to specific product |
| automaticOr | bool (optional) 0 or 1 |
When set to 1, automatic search with a OR instead of AND if there is no results with AND query
note : automaticOr is ignored if logicalType is specified |
| mobileFriendly | bool (optional) 0 or 1 | When set to 1, the response will return mobile compliant offers only |
| show_priceBounds | bool (optional) 0 or 1 | When set to 1, the response will return minimum and maximum prices from the resultset. 0 by default. |
| boostMobileResults | bool (optional) 0 or 1 | When set to 1, the response will return mobile friendly offers at the top of the resultset. Offers from merchants that are not considered mobile friendly will also be returned but below those which are mobile friendly. 0 by default. |
| imagesOverSsl | bool (optional) 0 or 1 | When set to 1, the response will return image links in https. 0 by default. |
| show_priceBounds | bool (optional) 0 or 1 | When set to 1, the response will return price min and price max values for the result set. |
| rebatePercentage | integer (optional) 0 to 100 | When set to 30 for example, the response will return offers that have a sale price discounted by 30% or more. |
Response Elements
Top level Elements
| Name | Summary |
|---|---|
| Categories | Contains a list of subcategories. Only returned if show_subcategories=1 is specified in the request and if there are available subcategories to return. Details of each subcategory are provided below.Attributes:
Categories will only be returned if they are enabled for the client. The element will be empty elsewhere. The response will return a warning if categories are disabled in the client profile. |
| Refinements | Each Refinement element contains a list of RefineValue elements. Only returned if category is specified in the request, there are available Refinements to return and that show_refinements is true.Attributes:
|
| Products | Contains each individual product offering (list of Product elements). Each Product element contains an Offer element:
Refinements are returned only if they are enabled for the client. The element are empty elsewhere. The response will return a warning if Refinements are disabled in the client profile. |
SubCategory Elements
| Name | Summary |
|---|---|
| Title | Contains the display name for the subcategory. |
| NumberOfProducts | Contains the number of products available for this subcategory. |
| Value | Contains the category ID for the subcategory that can be used as a value for the category request parameter. |
RefineValue Elements
| Name | Summary |
|---|---|
| Title | Contains the display name for the Refinement. |
| NumberOfProducts | Contains the number of products available for this Refinement. |
| Value | Contains the value for the Refinement that can be used as a value for the refinement request parameter. |
Offer Elements
- Common fields are used.
- All offer types can be contained in this service: offer types
Sample Response
The following is a sample response when you search for philips with the service.
