Search for products in our catalogs using a query string.

​
Category Prediction

The ValueChecker API is capable of predicting the correct category based on analysis of the search query string. Keep in mind this is highly dependent on the richness of the query string.

​
Examples of rich search queries:

  • 2008 lg washing machine front loader
  • Wifi/4G Galaxy Watch Sport T-Buckle graphite

Read more about Client Categories

​
Category Correction

When a search is made to a specified category (using one of the client_category or client_category_id request parameters) that the ValueChecker predicts with high certainty is the wrong category, a client feature (enabled by ValueChecker) automatically performs the search and returns results from the correct category.
As a feature you can request to enable/disable this automation correction depending on how your application user flow works (i.e. you wish to show the user potentially poor or no results from the requested category by design).
Additionally, if you have Category Correction enabled, you can pass an override parameter of force_client_category = true for specific search requests that will prevent any category analysis or switching.

​
Search Suggestions

For implementations that require fast or continuously updating results for a query search (examples: “search as you type”, instant display of related series/models, drop-down or tree population based on options etc..) you should call the search_suggestion endpoint.
It returns structured response data from our Master catalog at a faster rate than the extended search does. Additionally, calls to this endpoint have a much lower rate metering restriction. You can call it without any throttling.

For example: in a “search as you type” scenario, every keystroke (after the first X characters) can query this endpoint and you will get a response with product data based on the updated string as fast as the network allows which your implementation can then update/render to the user.
This endpoint returns a case insensitive, strictly matched result. Misspellings and mistakes are not considered nor automatically corrected.

Every request searches for results except when the search query matches a brand name, or the beginning of a brand name. In this case, due to the low specificity of the search, no results will be returned. For instance: if the endpoint is called with the query “Apple” for the client category “Mobile Phones”, the search query would match any Apple phone, so the chances of returning the product that is indeed being searched for is very low. Therefore, in this case, the search query needs to include at least two more characters after the brand name for the Search Suggestion endpoint to begin returning results. In the example above there will be iPhone results with a search query of “Apple ip”.

There is support for the user to also be allowed to define their own category which you pass to the API with the client_category parameter.

Important: This feature is only available for our catalog categories where we have pre-calculated replacement data. You can find this flag from the results of the client_categories endpoint where the category has a field and value of "has_replacement": true

example category
{
  "client_category_id": 11499,
  "client_category": "Smartwatches",
  "parent_client_category_id": 2427,
  "cid": 431051,
  "has_depreciation": true,
  "has_replacement": true,
  "acv_disabled": false,
  "show_closest_matches": false
}

Results: The result set may not be identical to the extended search results as we only query our Master products for this endpoint. We recommend you add functionality to allow a user to perform an extended search if they are not satisfied with these results or when we do not have any Master products matching their search query (empty resultset).

Language: The specification name (spec_name) values are currently only returned in lowercase English (please cast to the preferred format of your locale i.e. “Title Case” or “Camel Case” etc..).
Serving translations for the default locale of the requesting client (token) is under development and will be available in an upcoming non-breaking release.

CP: Fast Product Search Endpoint➜

​
Extended Search

This action performs a sequence of tasks (such as auto-correction for spelling typos, matching for Master products etc..) and analyses a large set of potential results. It returns a dataset of potential products within a series or product family (for example “Apple iPhone 11” will return the different storage variants of the standard, Pro and Pro Max models) or non-aggregate data from a variety of data sources (general product data, web results etc..).

This endpoint is metered and should not be called in a continuously updating implementation (such as “search as you type” etc..).

example response
{
  "results": [
    {
      "child_products": [],
      "pid": 1122795690,
      "client_category": "Laptops",
      "client_category_id": 2000,
      "product_name": "Asus Zenfone 9 8GB 5G 128GB White",
      "Product_picture_url": "https://img.valuechecker.net/,..j",
      "specs": [
        {
          "spec_id": 999,
          "spec_name_display": "Marke",
          "spec_value_display": "Asus",
          "spec_value_numeric": 1.0,
          "spec_name": "Marke"
        }
      ],
      "price": {
        "price": 790.0,
        "price_url": "https://www.belsimpel.nl/asus-zen…",
        "shop_count": 1,
        "price_date": "2022-12-06 15:58:52"
      }
    }
  ],
  "metadata": {
    "category": {
      "requested_client_category_id": 1234,
      "requested_client_category": "Laptops",
      "prediction_certainty": 0.9978,
      "predicted_client_category_id": 469,
      "predicted_client_category": "Mobiele Telefoon",
      "category_switched": true
    },
    "used_query": "asus zenfone 2015"
  }
}

​
Deprecation warnings

  • cid has been deprecated and will be removed in a future update. Please use the client_category_id directly instead.
  • category has been deprecated and will be removed in a future update. However, the client_category will return the same information.

If at least 1 pid is returned, use a pid to continue to Replacement Suggestions and Prices.

The response example also shows the Category Correction feature being activated where a query for “asus zenfone 2015” was performed in a requested category of “Laptops”. The certainty of 99% that this search should be performed in the category of Mobile phones (“Mobiele Telefoon” according to the client settings) triggered an automatic switch of categories for the search and response.

​
Reference Price

The Price returned here is a reference price. In many cases it is a near-live or recent price that ValueChecker has obtained from multiple internet sources (shops, search engines etc..). This price is not to be confused with the Replacement prices from the Replacement Suggestions and Prices.

​
Child Products

When ValueChecker finds products that are equivalent in technical specifications to a Master Product in our catalog but with minor variance in attributes (for example color), the response will consist of the Master Product with the variant products’ names in a nested list. The specifications of the child product(s) are identical to the Master Product with the only difference being in the product name. There is no difference in the replacement calculation.

By default, the response contains an empty child_products key (value: empty list).
example response "iPhone 10 grey"
{
  "product_name": "Apple iPhone X 64GB (2017)",
  "child_products": [
      "Apple - iPhone X 64GB - Space Gray",
      "Apple - iPhone X 64GB - Space Gray (AT&T)",
      "Apple - iPhone X 64GB - Space Gray (O2)",
  ],
  "specs": [
    ...,
  ]
}

​
Aggregated Prices (a.k.a. Clustered Prices)

For searches in non-core categories, the ValueChecker will search many popular shopping APIs (Google shopping for example) and collect all prices that match the search query. After clustering the prices into 3 buckets of low, medium and high, the data is available in the response for cases where you want to show average prices to the application users.

An example response for a search for “Levis bluejeans”:

note that no category information is requested.

{api_url_path}/product_search?query=Levis bluejeans

Response (excerpt)
{
  "results": [
    {
      "pid": 1739972236,
      "cid": 135,
      "category": "Clothes",
      "client_category": "Clothes",
      "client_category_id": 3000,
      "product_name": "levi's blue jeans",
      "product_picture_url": "https://img.valueecker.net/...jpg",
      "price": {},
      "price_clusters": {
        "low": {
          "udc_id": 163332,
          "pid": 1739972236,
          "group": "low",
          "price": 51,
          "count": 7,
          "percentage": 0.28,
          "min_price": 39,
          "max_price": 61
        },
        "medium": {
          "udc_id": 163333,
          ...
        },
        "high": {
          "udc_id": 163334,
          ...
        }
      },
      "child_products": [],
      "child_product_contents": []
    }
  ],
}

The first item in the “results” object will have the keys”

  • price_clusters: the object with the price cluster information.
  • udc_id: This is the identifier of the product with the attached cluster weight: low, medium or high. There are 3 different udc_ids per product that can be used to create an appraisal.
  • price: The median price of the cluster. Use this value as the cluster price.
  • percentage: Ratio of the number of prices in the cluster compared to all prices found for the search.
CP: Extended Product Search Endpoint➜