Search API Request (Powered by Google)
Overview
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.
Area
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" }
Collection
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 }
Query
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 }
Refinement
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)
Skip
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 }
Sorts
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": [
"colorFamilies",
"price",
"attributes.SKU_SIZE"]
{
"query": "jeans",
"collection": "productsClothing",
"area": "Production",
"pageSize": 10,
"dynamicFacet": false,
"skip": 0,
"responseMask": [
"rating",
"variants.priceInfo.price"
],
"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"
}
}