Eureka Suggestion API

The Suggestion API offers query recommendations as users type into a search bar. It analyzes the input text and returns a list of relevant suggestions in real time, based on user history and other contextual information such as category and brand. This feature notably improves the user experience, accelerating the search process and effectively directing users to their intended queries.

Endpoint

GET https://{domain_name}/api/web/suggestions/query

Visit our Postman collection to test this request.

When the request is sent 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.

Request Parameters

Parameter	Description	Data Type	Sample	Required
q	Query String that will be searched	String	q=sneakers	Yes
p	This is your partner ID. Navigate to InOne > Inone Settings > Account Settings to copy your partner ID.	String	10000000	Yes
l	Locale is required to get your products in the current language of the website.	String	l=en_US	Yes

The q parameter in the query should be between 2 and 280 characters. Otherwise, a validation exception will occur.

Sample Responses

Parameter	Definition
status	It is the field that shows the result of the suggestion. This field can be: - Success: Suggestion API response is valid. - Error: Unexpected internal server errors. - Invalid: Suggestion API returns a Validation Exception. The request is invalid. - BusinessException: Eureka Search API returns a Business Exception. Details are shared in Validation Exceptions section.
data	It is the object that stores the suggested phrases and their types resulting from the given query.
validations	When the request is incorrect (HTTP 4XX), this field contains an array of type and message details.

200 Search

{ 
  "status": "Success",
  "data": [
    {
      "phrase": "..."
      "phraseType": "..."
    }, ...
  ],
  "error": null,
  "validations": null
}

500 Internal Server Error

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

400 Validation Exception

{
  "status": "ValidationException",
  "data": null,
  "error": null,
  "validations": [
    "..."
  ]
}

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 seconds."
    },
    "validations": null,
    "appliedSearchStrategy": null,
    "merchandisingRuleBanner": null
}

Fail Records Messages

Business Exceptions

Message	Definition	HTTP Code
PartnerConfigNotFound	The partner config cannot be retrieved from the cache.	400

Validation Exceptions

Message	Definition	HTTP Code
QueryNotFound	q parameter is not provided in the request.	400
QueryInvalidFormat	The request provides an incorrect query format.	400
QueryInvalidLength	The query must contain between 2 and 280 characters.	200

Rate Limit Exceeded Exception

Message	Definition	HTTP Code
RateLimitExceeded	Indicates that the request rate exceeded the allowed limit per account-locale pair.	429

Please note that the Suggestion API has a rate limit of 450 requests per second (RPS) per account-locale pair. If you would like to request a higher limit, contact the Insider One team.