Eureka Search API

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

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

Requirements for Search API

• The Insider One team should activate Eureka.
• Product Catalog integration methods (XML, Catalog API, and Clickstream) should be created for product details.
• Eureka settings, such as facets, sorting options, synonyms, URL redirections, etc., should be defined on the Insider One's InOne panel.

Endpoint 

GET https://ineureka.api.useinsider.com/api/web/search

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, for security reasons, an authentication exception is thrown when the request is sent. 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. These types select the sorting algorithm for the searched products. 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 One's InOne panel.

Sample Filter Result Regarding the Filter Config

Sample filter request:

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

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

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

The field values you can use for facet filtering are 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; each must be stated separately. Also, the field can take multiple values separated by a tilde (~). Field values should be different; if there is more than one value, they should be separated according to the filter pattern.

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

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

For 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

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 
}

429 Rate Limit Exceeded Exception

{
    "status": "RateLimitExceeded",
    "data": null,
    "redirection": null,
    "partnerResources": null,
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded. Please retry after 1 second."
    },
    "validations": null,
    "appliedSearchStrategy": null,
    "merchandisingRuleBanner": 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

• Rate Limit Exceeded Exception