Welcome to the Kelkoo Group Customer Service

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.

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:

  • price_ascending
  • price_descending
  • totalprice_ascending
  • totalprice_descending
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 :

    1. all the offers matching term 1 AND term 2
    1. all the offers matching term 1 OR term 2
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 String (true/false default true) specify if you want automatic search with a OR instead of AND if there is no results with AND query
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:

  • total_subcategories: integer indicating total subcategories returned

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:

  • label: The display value of the refinement.
  • name: An attribute specifying the display name for the refinement key
  • totalvalues: An attribute specifying the number of values returned for this refinement key
Products Contains each individual product offering (list of Product elements). Each Product element contains an Offer element:

  • searchOperator: the type of search performed in case of a list of keyword
    • “and” : the search is on exact term (keyword1 and keyword2 and keyword3)
    • “or”  : the search have been performed on each keyword separately (keyword1 or keyword2 or keyword3)
  • totalMerchantsAvailable: The number of merchants available in the query
  • totalResultsAvailable: The number of query matches in the database
  • totalResultsReturned: The number of query matches returned. This may be lower than the number of results requested if there were fewer total results available
  • firstResultPosition: The position of the first result in the overall search
  • EAN: The EAN if specified in the query
  • highestPrice: The hightest price found related to query
  • lowestPrice: The lowest price found related to query
  • currency: The currency used to display offer prices

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.

Related Web Services

Catalog Search