Search API Request (Powered by Google)


Groupby’s Product Discovery Platform powered by Google Cloud Retail AI provides personalized search and recommendations to your shoppers based on their interaction with your site.

To enable this, GroupBy requires your Product catalog and Historic user events (beacon data) to train the machine learning models that will power your search and recommendations.

Any new user event can be captured by the GroupBy beacons. Beacons will now also capture details from Retail search and feed this information back into Google’s re-ranking models, to improve the search quality and personalize the search results for returning shoppers.


The area you wish to fire against, production, staging, etc… If not specified, the Production area will be used (and if one doesn’t exist, an error will be returned).

JSON Reference:

{ "area": "Development" }


The collection to use. If you don’t pass this parameter, default will be the collection used. This is case sensitive and should be same as your collection name.

JSON Reference:

{ "collection": "productsStaging" }

Custom Url Param

Sets any additional parameters that can be used to trigger rules. Takes a name and a value.

JSON Reference:

Custom URL parameters separated by ~ in the form:

{ "customUrlParams": [ { "key": "region", "value": "east" } ] }

Response Mask

Specify which fields should be returned on each record that comes back from the engine. You may specify more than one field. If the parameter is omitted, or if you specify \* all fields defined as retrievable fields by the ETL process will be returned. If this parameter is an empty string \"", the search service will return only the id and title field. The id and title fields are always returned.

JSON Reference:

{ "responseMask": [ "categories", "brand", "height" ] }

Page Size

Page size. Default is 10.

JSON Reference:

{ "pageSize": 8 }


Set a search string. If query is blank all records are considered. There are some limits enforced on the search string, it:

     - must not exceed 60 characters
     - must not exceed 10 terms.

If the limits are exceeded, the search string is truncated until all limits are satisfied. For example, the following search string

 The quick brown fox jumps over the colorful wide bridge into the cold river.

will get truncated to:

 The quick brown fox jumps over the colorful wide bridge

The terms the, cold, and river were truncated because the term limit was exceed, and into was also removed because the resulting string exceeded the character limit. Stop words are included in the string when determining if limits are exceeded. If there is only one term and it exceeds the character limit, the query will fail.

JSON Reference:

{ "query": "gloves" }

Dynamic Faceting

The dynamic faceting dynamicFacet flag in the request requests the most relevant Navigations (aka facets/filters) for a particular search or browse request. It is recommended for this to always be set to true

JSON Reference:

{ "dynamicFacet": true }


Add a refinement. Please note that refinements are case-sensitive

JSON Reference:

Value and range refinements are both appended to an array on the refinements field. Note the ‘type’ field, which marks the refinement as either a value or range refinement.

{ "refinements": [ {"navigationName": "rating","displayName": "Rating", "type": "Range", "low": "1.0", "high": "2.0", "or": true},
{"navigationName": "brand", "displayName": "Manufacturer","type": "Value",  "value": "Nike", "or": true } ] }

Required parameters for all refinements are as follows: navigationName - the attribute name to refine on as it exists in the data displayName - a display name for the navigation (defined in command center, or as shown in the search response type - whether the refinement is a Value (string) or Range (numeric) value - the selected value of a Value type refinement. Example for navigationName = color, value would be blue low - the minimum value of the selected range type refinement high - the maximum value of the selected range type refinement or - whether the navigation can be multi-selected (defined in Command Center or shown in the response from a previous call)


Tell the search service to offset by N records. For example, if N is 10, the records returned will start at 11.

JSON Reference:

{ "skip": 10 }


Specifies the sort order applied to the fields in the order specified. If no sort criteria are specified, the default is to sort by relevance. There is a special sort field _relevance, which also specifies sorting by relevance. It is possible to specify multiple sort criteria. The criteria order matters, as the records will be sorted by the first criteria and then any matches will be tie-broken using the next criteria. Given an example where the sort is specified as category then _relevance, results will be sorted first by category and relevance will only affect the order between records that have the same category. Records can also be sorted by a specific ID as well when you want to return items in a specific order. If a record ID is included as a sort, but that record not a part of the result set, that item will not be included (unlike push to top). There is a limit of 1000 id’s that you can sort by. Any ID’s beyond this limit will be ignored. ID sort can also be used with other types of sorts.

Please note, sorting is based on the actual value in the record. For example, if sorting on price, and price is a Range navigation, the records will be sorted according to the actual price value in the record and not the bucket value.

The order field can be set to either Ascending or Descending. When sorting by relevance, the order is always Descending. For any other field, the default order is Ascending.

JSON Reference:

{ "sorts": { "field": "price", "order": "Descending" } }
{ "sorts": [{ "field": "_relevance" }, { "field": "price", "order": "Descending" }] }
{ "sorts": [{ "field": "brand", "order":"Ascending" }, { "field": "_relevance" }, { "field": "price" }] }

Variant Rollup Keys

The variantRollupKeys array in the request allows us to request all values for all the variants of a product based of this key. For example, colors, sizes or prices. (This will return variantRollupValues

JSON Reference:

	"variantRollupKeys": [
  "query": "jeans",
  "collection": "productsClothing",
  "area": "Production",
  "pageSize": 10,
  "dynamicFacet": false,
  "skip": 0,
  "responseMask": [
  "refinements": [
      "navigationName": "rating",
      "displayName": "rating",
      "type": "Range",
      "low": "4.0",
      "high": "5.0",
      "or": true
      "navigationName": "brand",
      "displayName": "Brand",
      "type": "Value",
      "value": "Earl Jeans",
      "or": true
      "navigationName": "brand",
      "displayName": "Brand",
      "type": "Value",
      "value": "7 For All Mankind",
      "or": true
  "sorts": {
    "field": "price",
    "order": "Descending"