Server-side integration

Connection stages

1. Basic integration

The Rocket Search integration requires basic Retail Rocket integration, which includes transferring the product database and setting up user behavior tracking.

For filters and sorting to work correctly in search results, relevant attributes must be transferred in the product database (for example, brand, price, color, category, rating, etc.).

Basic integration stages

For more information about starting integration with Retail Rocket, see the corresponding section.

Testing requests

You can use the interactive API tester in the documentation to test API requests:

2. Configuring server-side interaction

Rocket Search server-side integration lets you receive search results and previews directly through the API. This option is suitable for projects that require complete control over search display and the processing of user scenarios on the server side.

info

To use the API, follow the general integration principles and transfer user session data correctly (see session management).

3. API integration

At this stage, the product is connected to your platform through the server API. The methods for obtaining search data, working with filters, and sending user events are described below.

Integration process

Getting search results

Use the following method to retrieve full search results:

POST https://search.retailrocket.net/rocketsearch/v5/partner/{partnerId}/phrase/{phrase}/page/

Parameters

Parameter	Type	Required	Description
phrase	string	Yes	Search phrase using URL encoding
page	number	Yes	Page number, starting from 1
pageSize	number	Yes	Number of products per page
lang	string	Yes	Store language
stock	string	No	Warehouse ID for multiregional stores
sorting	string	No	Selected sorting ID
linkName	string	Yes*	Name of the session identifier
linkValue	string	Yes*	Value of the session identifier

Request body

Pass an empty filter array in the first request:

{
  "filters": []
}

Request example

curl -X POST 'https://search.retailrocket.net/rocketsearch/v5/partner/59908d02c7d013ce40de715a/phrase/monitor/page/?apiKey=testKey&page=1&pageSize=24&lang=en&stock=14&linkName=session&linkValue=42' \
  -H 'Content-Type: application/json' \
  -d '{"filters": []}'

Response example (products found)

{
  "resultsPage": {
    "productsCount": 407,
    "pagesCount": 17,
    "contentId": "5831a77b-6747-47c5-b10b-0c8e16c1a342",
    "products": [
      {
        "productId": 1193253
      },
      {
        "productId": 1209366
      }
    ],
    "filters": [
      {
        "checkBoxFilter": {
          "filterId": "brands",
          "title": "Manufacturer",
          "retrievedValues": [
            {
              "valueId": "brand_0",
              "title": "brand_title_0",
              "count": 74,
              "isSelected": false
            },
            {
              "valueId": "brand_1",
              "title": "brand_title_1",
              "count": 23,
              "isSelected": false
            }
          ]
        }
      }
    ],
    "sortings": [
      {
        "sortingId": null,
        "title": "By relevance"
      },
      {
        "sortingId": "price_asc",
        "title": "Lowest price first"
      }
    ],
    "selectedSortingId": null
  }
}

Empty results

If the search phrase has no results, the response contains an emptyResultsPage object.

{
  "emptyResultsPage": {
    "contentId": "49889283-1f23-4b18-afec-1daaa91b21aa"
  }
}

Category redirect

If the search phrase matches the name of a category, the platform can determine that it is more appropriate to navigate to the category page in the store instead of showing search results.

In this case, the search results response contains the following object:

{
  "categoryRedirect": {
    "contentId": "49889283-1f23-4b18-afec-1daaa91b21aa",
    "category": {
      "categoryId": 3431
    }
  }
}

tip

If the store is integrated through the Product API, categoryPath can be used instead of categoryId.

Working with filters and sorting

After the first request, you receive a list of available filters and sorting options. For subsequent requests, pass the selected filters in filters and the sorting option in the sorting query parameter.

Filter format in a request

The following filter value types are supported:

radioButtonFilterValue

{
  "radioButtonFilterValue": {
    "filterId": "categories",
    "selectedValueId": "3883"
  }
}

checkBoxFilterValue

{
  "checkBoxFilterValue": {
    "filterId": "brands",
    "selectedValueIds": [
      "brand_0",
      "brand_1"
    ]
  }
}

intervalFilterValue

{
  "intervalFilterValue": {
    "filterId": "price",
    "selectedMin": 10000,
    "selectedMax": 100000
  }
}

ratingFilterValue

{
  "ratingFilterValue": {
    "filterId": "rating",
    "selectedValues": [
      3,
      4
    ]
  }
}

switchFilterValue

{
  "switchFilterValue": {
    "filterId": "available",
    "value": true
  }
}

Combined `filters` example

{
  "filters": [
    {
      "checkBoxFilterValue": {
        "filterId": "brands",
        "selectedValueIds": [
          "brand_0",
          "brand_1"
        ]
      }
    },
    {
      "intervalFilterValue": {
        "filterId": "price",
        "selectedMin": 10000,
        "selectedMax": 100000
      }
    },
    {
      "switchFilterValue": {
        "filterId": "available",
        "value": true
      }
    }
  ]
}

Filter formats in a response

The API returns filters as typed objects.

radioButtonFilter

{
  "radioButtonFilter": {
    "filterId": "categories",
    "title": "Category",
    "retrievedValues": [
      {
        "valueId": "12",
        "title": "monitors",
        "count": 404
      }
    ],
    "selectedValueId": null
  }
}

checkBoxFilter

{
  "checkBoxFilter": {
    "filterId": "brands",
    "title": "Manufacturer",
    "retrievedValues": [
      {
        "valueId": "brand_0",
        "title": "brand_title_0",
        "count": 74,
        "isSelected": true
      }
    ]
  }
}

intervalFilter

{
  "intervalFilter": {
    "filterId": "price",
    "title": "Price",
    "retrievedMin": 7699,
    "retrievedMax": 224100,
    "selectedMin": 10000,
    "selectedMax": 100000
  }
}

ratingFilter

{
  "ratingFilter": {
    "filterId": "rating",
    "title": "Rating",
    "retrievedValues": [
      {
        "value": 4,
        "count": 43,
        "isSelected": true
      }
    ]
  }
}

switchFilter

{
  "switchFilter": {
    "filterId": "available",
    "title": "In stock only",
    "value": true
  }
}

Getting search preview

Use the method to retrieve preview data (products, categories, suggestions):

GET https://search.retailrocket.net/rocketsearch/v5/partner/{partnerId}/phrase/{phrase}/preview/

Parameters

Parameter	Type	Required	Description
phrase	string	Yes	Search phrase using URL encoding
lang	string	Yes	Store language
stock	string	No	Warehouse ID
linkName	string	Yes*	Name of the session identifier
linkValue	string	Yes*	Value of the session identifier

Search preview response example

{
  "contentId": "49889283-1f23-4b18-afec-1daaa91b21aa",
  "products": [
    {
      "productId": 1193253
    },
    {
      "productId": 1209366
    }
  ],
  "suggestions": [
    "system unit",
    "gaming system unit"
  ],
  "categories": [
    {
      "categoryId": 495
    },
    {
      "categoryId": 5986
    }
  ]
}

suggestions is an array of suggestion strings for the search phrase.

categories is an array of objects for redirecting to a category.

Pagination

The page and pageSize parameters are used for pagination in search results:

?page=1&pageSize=24

When navigating to the next page:

?page=2&pageSize=24&contentId=61010bd1-4ed1-4fac-9699-3b8ea39d5f00

Important

The contentId parameter fixes the results, ensuring that results are loaded sequentially. It is used only when loading subsequent batches of products; its value is taken from the previous request's response.

Sending search interaction data

For correct analytics and search training, send interaction events for search results and suggestions.

Tracking interaction events

For more information about the methods, see Search interaction.

Connection stages​

1. Basic integration​

Testing requests​

2. Configuring server-side interaction​

3. API integration​

Integration process​

Getting search results​

Parameters​

Request body​

Request example​

Response example (products found)​

Empty results​

Category redirect​

Working with filters and sorting​

Filter format in a request​

radioButtonFilterValue​

checkBoxFilterValue​

intervalFilterValue​

ratingFilterValue​

switchFilterValue​

Combined filters example​

Filter formats in a response​

radioButtonFilter​

checkBoxFilter​

intervalFilter​

ratingFilter​

switchFilter​

Getting search preview​

Parameters​

Search preview response example​

Pagination​

Sending search interaction data​

Connection stages

1. Basic integration

Testing requests

2. Configuring server-side interaction

3. API integration

Integration process

Getting search results

Parameters

Request body

Request example

Response example (products found)

Empty results

Category redirect

Working with filters and sorting

Filter format in a request

radioButtonFilterValue

checkBoxFilterValue

intervalFilterValue

ratingFilterValue

switchFilterValue

Combined `filters` example

Filter formats in a response

radioButtonFilter

checkBoxFilter

intervalFilter

ratingFilter

switchFilter

Getting search preview

Parameters

Search preview response example

Pagination

Sending search interaction data