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
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: |
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 |
The Suggestion API has a rate limit of 450 requests per second (RPS) per account-locale pair. To request a higher limit, contact the Insider One team.
Decommissioning a Eureka API Integration
Stopping or deactivating a Eureka campaign in the InOne panel doesn't stop or remove your integration. Eureka usage is request-based, so every request your integration sends to the Search API, Category API, or Suggestions API counts toward usage until you remove it. For details on how requests are counted, see Eureka Usage Measurement.
Stop the requests
To stop your integration from sending requests:
Remove the integration that calls Eureka endpoints from your frontend, backend, and any proxies.
Disable server-side jobs or services that call Eureka endpoints.
Deploy the change to every environment where the integration is active.
Note: If your mobile app calls Eureka endpoints, older app versions keep sending requests until your users update to a version without the integration.
Verify decommissioning
To confirm the integration no longer sends requests:
Check your application and server logs for new requests to Eureka endpoints.
Navigate to Reports > Usage Analytics > Eureka API Request Volume and confirm the request count stops increasing after the next reporting period.
For integration setup, see Eureka Search API Integration and Eureka Category Merchandising API integration.