Eureka Search API

Overview

Eureka’s API (Search API) lets you quickly and smoothly implement our search engine within your website(s), or mobile application(s). Insider's powerful search engine powers millions of queries every month, and is capable of delivering relevant results in under 150-400 ms regardless of the location.

The first step is to send your data in the correct format to Insider. Eureka will return the results in JSON. The response will include products that match the search criteria, available facet options to further refine the results and any configured merchandising content.

Requirements for Search API

• Insider product catalog integration methods (XML, Catalog API and Clickstream) should be created for product details.
• Data collection should be activated by Insider team.
• Eureka should be activated by Insider team.
• The facets & filters, synonyms, URL redirections should be defined on Insider's InOne panel.

Endpoint 

You can use two domains to use the Search API:

• eureka.api.useinsider.com
• ineureka.api.useinsider.com

GET https://{domain_name}/api/web/search

When the request is sent in this way, an authentication exception is thrown for security reasons. Therefore, when sending the request, you need to set the X-AUTH-TOKEN field in the header with the token shared with you and send the request.

The only difference between GET and POST requests is that the values sent as URL parameters in GET requests must be sent as JSON body in POST requests as you can see below:

{
  "q": "SEARCH_QUERY",
  "p": "PARTNER_ID",
  "l": "LOCALE",
  "c": "CURRENCY"
}

Bear in mind that when the request is sent, an authentication exception is thrown for security reasons. In order to avoid this, you need to set the X-AUTH-TOKEN field in the header with the token while sending the request.

Request Parameters

Sorting

The st parameter in the request can only have one value from the predefined sorting types. Using these types, the sorting algorithm for the searched products is selected. Depending on your data, the sorting types can be active or inactive, you can view these settings on the InOne panel.

Filters

Search results can be filtered using fields in filter settings defined in faceting on the Insider's InOne panel.

Sample Filter Result Regarding the Filter Config

Sample filter request:

&a=category~Skin~Body Lotions&a=price~5~10

In the result of this filter request, you can see the matched facets in the related result section as below:

{
  "itemProperties": {
    "item_card": {
      "price": {
        "EUR": 7.75,
        ...
      },
      "category": [
        "Skin",
        "Body Lotions",
        ...
      ],
      "in_stock": 1,
      ...
    },
    ...
  },
  ...
}

The field values that you can use for facet filtering is provided under data.aggregations in the result.

[
  {
    "name": "price",
    "label": "Price",
    "style": "Slider",
    "items": [
      {
        "name": "0~5",
        "min": 0.0,
        "max": 5.0
      },
      {
        "name": "5~10",
        "min": 5.0,
        "max": 10.0
      },
      ...
    ],
    "sequence": 1,
    "itemOrderType": "KeyAsc"
  },
  {
    "name": "category",
    "label": "Category",
    "style": "List",
    "items": [
      {
        "name": "Skin",
        "selected": true,
        "documentCount": 66
      },
      {
        "name": "Body Lotion",
        "selected": true,
        "documentCount": 61
      },
      ...
    ],
    "sequence": 2,
    "itemOrderType": "CountDesc"
  },
  {
    "name": "in_stock",
    "label": "In Stock",
    "style": "Checkboxes",
    "items": [
      {
        "name": "1",
        "selected": false,
        "documentCount": 12
      },
      ...
    ],
    "sequence": 3,
    "itemOrderType": "CountDesc"
  },
  ...
]

"a" parameter should be passed to the request as a query string when the request method is GET, or it should be passed as a list of strings when the request method is POST. The "a" can take multiple fields and each must be stated separately. Also, the field can take multiple values separated by a tilda (~). Field values should be different and if there is more than one value, they should be written by separating them according to the filter pattern.

?a={field}~{value}&a={field}~{value}

{"a": ["{field}~{value}", "{field}~{value}"]}

For the filters with numeric data types such as Slider style, there should be only two values min and max.

{field}~{minValue}~{maxValue}

Sample Filter Parameters

&a=brand~Mybrand

&a=category~Birds~Cats~Dogs

&a=price~50~100

&a=brand~Mybrand&a=price~50~100

Sample Responses

API Responses

200 Search

{ 
  "status": "Success",
  "data": {
    "items": [...],
    "aggregations": [...],
    "navigation": {...},
    "noResultPageText": "...",
    "sortings": [...]
  },
  "redirection": null,
  "partnerResources": {...},
  "error": null,
  "validations": null,
  "appliedSearchStrategy": "..."
}

200 Recommendation

{ 
  "status": "SuccessFallback",
  "data": {
    "items": [...],
    "brands": [...],
    "categories": [...],
    "noResultPageText": "...",
    "defaultSortingType": null
  },
  "redirection": null,
  "partnerResources": {...},
  "error": null,
  "validations": null,
  "appliedSearchStrategy": "..."
}

400 Validation Exception

{ 
  "status": "Invalid", 
  "data": null, 
  "redirection": null, 
  "partnerResources": null,
  "error": null,
  "validations": [
    {
      "type": "...",
      "message": "..."
    }
  ],
  "appliedSearchStrategy": null
}

400 Business Exception

{ 
  "status": "BusinessException",
  "data": null,
  "redirection": null,
  "partnerResources": null,
  "error": {
    "code": "...",
    "message": "..." 
  },
  "validations": null,
  "appliedSearchStrategy": null 
}

500 Internal Server Error

{ 
  "status": "Error",
  "data": null,
  "redirection": null,
  "partnerResources": null,
  "error": {
    "code": "500 INTERNAL_SERVER_ERROR",
    "message": "..." 
  },
  "validations": null,
  "appliedSearchStrategy": null 
}

Fail Records Messages

• Business Exceptions

• Validation Exceptions