Searching for products

The novomind iSHOP REST API exposes the novomind iSHOP search engine as REST service.

GET <SHOP>/ishop-api/search?term=Bett

returns a list of products matching the search term. The API service contains the same logic as the shop (like synonyms or fuzzy logic). I.e. these two search requests will return nearly the same results:

GET <SHOP>/ishop-api/search?term=Bett
GET <SHOP>/ishop-api/search?term=Bettt

Explain flag

It is possible to append an explain flag to the search request: GET <SHOP>/ishop-api/search?term=Bett&explain=true

Next to the result (the list of products), this will return an explanation for each result. The explanation contains the reason why a product has been returned (The "traces") and the score by which the position of the returned product on the list is determined.

Complex search requests

When using post requests to access the search API, additional filters and sorters are returned and can be set. The first response always contains the available filters and sorters. Additional requests may contain the selected filters and sorters. Here an example:

The first request: POST <SHOP>/ishop-api/search?term=Bett

returns this json response:

{
  "filterQuery": {
    "categoryFilter": null,
    "selectedSorter": null,
    "priceFilter": {
      "displayName": "Price",
      "selectedFrom": { "amount": 100, "currencyCode": "EUR" },
      "selectedTo": { "amount": 2000, "currencyCode": "EUR" },
      "reduced": false,
      "suggestions": [
        {
          "from": { "amount": 100, "currencyCode": "EUR" },
          "to": { "amount": 500, "currencyCode": "EUR" },
          "count": 5,
          "selected": false
        },
        {
          "from": { "amount": 500, "currencyCode": "EUR" },
          "to": { "amount": 2000, "currencyCode": "EUR" },
          "count": 12,
          "selected": false
        },
      ],
      "min": { "amount": 100, "currencyCode": "EUR" }
      "max": { "amount": 2000, "currencyCode": "EUR" },
    },
    "customFilters": [
      {
        "urlName": "age",
        "displayName": "Age in years",
        "min": 2,
        "max": 99,
        "selectedMin": null,
        "selectedMax": null
      }
    ],
    "sorters": [
      { "id": "topseller", "displayName": "UnusedSorterDisplayName", "descending": false },
      { "id": "price", "displayName": "UnusedSorterDisplayName", "descending": false }
    ],
    "attributeFilters": [
      {
        "displayName": "Color",
        "attributeName": "color",
        "values": [
          { "value": "blue", "displayName": "Blue", "count": 6 },
          { "value": "yellow", "displayName": "Yellow", "count": 9 },
          { "value": "green", "displayName": "Green", "count": 2 }
        ],
        "selectedValues": []
      },
      {
        "displayName": "Brand",
        "attributeName": "brand",
        "values": [
          { "value": "Apple", "displayName": "Apple", "count": 12 },
          { "value": "Sony", "displayName": "Sony", "count": 5 }
        ],
        "selectedValues": []
      }
    ]
  },
  "content": [
    {
    ...

Select the price filter:

The filterQuery is what we have to sent back via a succeeding post request. First we want to select a maximum price for the returned products. For this we set the "selectedTo" property to our new value. So the request body looks like this:

{
  "priceFilter": {
    "selectedFrom": { "amount": 100, "currencyCode": "EUR" },
    "selectedTo": { "amount": 1000, "currencyCode": "EUR" }
  }
}

Note that we can skip most of the other properties of the filterQuery as we either leave them to the default or they are not necessary to construct the filter in the backend (like the displayName or the suggestions). The response will contain the filtered list of products and filters. I.e. if there are no green products that cost below 10 €, the filter value "green" is removed.

Select an attribute filter:

Next we want to filter by attribute - but we also want to keep our price filter. So we attach one of the attribute filters and the new request body looks like this:

{
  "priceFilter": {
    "selectedFrom": { "amount": 100, "currencyCode": "EUR" },
    "selectedTo": { "amount": 1000, "currencyCode": "EUR" }
  }
  "attributeFilters": [
    {
      "attributeName": "color",
      "selectedValues": [
        { "value": "blue", "displayName": "Blue", "count": 6 }
      ]
    }
  ]
}

Again we only have to set the "selectedValues" property and can spare the rest out.

Set the category filter:

To restrict our result to a specific category we can now set the category filter:

{
  "priceFilter": {
    "selectedFrom": { "amount": 100, "currencyCode": "EUR" },
    "selectedTo": { "amount": 1000, "currencyCode": "EUR" }
  }
  "attributeFilters": [
    {
      "attributeName": "color",
      "selectedValues": [
        { "value": "blue", "displayName": "Blue", "count": 6 }
      ]
    }
  ],
  "categoryFilter" : {
    "categoryId" : "3532757"
  }  
}

Set custom filters:

The novomind iSHOP API does also support custom filters that are defined individually for each shop. In general these filters are handled like all other filters. In the following example a custom filter named "age" is sent back to the server. Obviously these filters may differ for every shop.

{
  "priceFilter": {
    "selectedFrom": { "amount": 100, "currencyCode": "EUR" },
    "selectedTo": { "amount": 1000, "currencyCode": "EUR" }
  }
  "attributeFilters": [
    {
      "attributeName": "color",
      "selectedValues": [
        { "value": "blue", "displayName": "Blue", "count": 6 }
      ]
    }
  ],
  "categoryFilter" : {
    "categoryId" : "3532757"
  },  
  "customFilters": [
    {
      "urlName": "age",
      "selectedMin": 12,
      "selectedMax": 18
    }
  ]
}

Select a sorter

With every response a set of filters is returned. A request to the search API may contain a selected sorter and additionally a "descending" flag to invert the filter:

{
  "priceFilter": {
    "selectedFrom": { "amount": 100, "currencyCode": "EUR" },
    "selectedTo": { "amount": 1000, "currencyCode": "EUR" }
  }
  "attributeFilters": [
    {
      "attributeName": "color",
      "selectedValues": [
        { "value": "blue", "displayName": "Blue", "count": 6 }
      ]
    }
  ],
  "categoryFilter" : {
    "categoryId" : "3532757"
  },  
  "customFilters": [
    {
      "urlName": "age",
      "selectedMin": 12,
      "selectedMax": 18
    }
  ],
  "selectedSorter" : {
    "id" : "price",
    "descending" : true
  }
}