Advanced Features

Examples are given in JSON format. SuggestGrid API Clients use the same structures in their conventions. Refer to their documentations for examples.

Recommendation and similarity methods can have a number of valuable parameters that makes SuggestGrid a full-feature and flexible service.

However, all the parameters listed below are optional. For recommendation and similarity methods only item or user ids are required. Therefore, you can skip this section if you just want a quick start.

Types must be created before asking for recommendations. When a type or types parameter is not specified, SuggestGrid returns responses making use of all the actions across all the types.

When recommendations or similarities from one or a couple of types is wanted, which we recommend to be done so, a type or types parameter could be added. If provided, yype parameter must have a string value and types parameter must have a vector of strings value.

By default, SuggestGrid returns 10 responses. In case a different number of results are requested, a size parameter with positive integer value could be added.

In some cases some users or items may not wanted to be included in results. SuggestGrid supports this feature with except parameter. This paramter can except a single id or multiple ids in a vector, that will not be included in the results.

Recommnedation requests can included similars parameters. For recommended items, similar item or similar items parameters that can have a single id or multiple ids respectively can be provided. Similarly, for recommended users, similar user or similar users parameters that can have a single id or multiple ids respectively can be provided.

When provided SuggestGrid scores the results respectively and makes use of both recommendation and similarity scores. Using this parameter, very valuable recommendations can be requested. For example, if a user is on a page of an item on a customer's application, our customer can ask for recommended items for that user that are similar to the item they are looking to.

fields is an optional parameter in recommendation or similarity requests. It's an array of parameters. These parameters will be included in objects of similars and recommendations arrays in responses. In case these parameters are not found in returned object metadata null will be placed in parameter values. The default value is fields: ["id"].

An example is below:

A similar users request:

$ curl -XPOST https://{account}:{key}@{app-uuid}.{region}.suggestgrid.space/v1/type/_similar/_users/42 --header "Content-type:application/json" --data '
  {
      "size": 3
  }'

{"similars":{"count":3,"users":[{"id":"42"},{"id":"821"},{"id":"9"}]}}

The same request with fields: ["name"]:

$ curl -XPOST https://{account}:{key}@{app-uuid}.{region}.suggestgrid.space/v1/type/_similar/_users/42 --header "Content-type:application/json" --data '
  {
      "size": 3,
      "fields": ["name"]
  }'

{"similars":{"count":3,"users":[{"id":"42","name":"John Doe"},{"id":"821","name":null},{"id":"9","name":"Alex Smith"}]}}

In this documentation <field> will be used for metadata fields and <value> will be used for values of metadata fields.

For example given the metadata for an item below:

{"id": 1, "name": "Example SuggestGrid Item", "price": 199, "tags": ["new", "white", "top_seller"]}

"id", "name", "price", and "tags" are <field>s.

On the other hand, 1, "Example SuggestGrid Item", 199, and ["new", "white", "top_seller"] are these fields' respective <value>s.

Valid filters are represented with <filter>.

Higher-order filters that takes other filters.

and filter

Checks if all of the <filter>s are truthy.

example:

"and": [<filter>, ...]
or filter

Checks if at least one of the <filter>s are truthy.

example:

"or": [<filter>, ...]
not filter

Checks if the <filter> is falsy.

example:

"not" : <filter>
equal filter

Checks if the value of <field> is "equal" to <value>.

example:

"equal": {
    "<field>": "<value>"
}
not_equal filter

Checks if the value of <field> is "not equal" to <value>.

example:

"not_equal": {
    "<field>": "<value>"
}

which is equivalent to:

"not": {
    "equal": {
        "<field>": "<value>"
    }
}
not_null filter

Checks if the value of <field> is not equal to null, or is "not null".

example:

"not_null": "<field>"

which is equivalent to:

"not": {
    "equal": {
        "<field>": null
    }
}

Please note that if you don't provide any value to a filter their value is null.

greater filter

Checks if the value of <field> is "greater" than <value>.

example:

"greater": {
    "<field>": "<value>"
}
greater_equal filter

Checks if the value of <field> is "greater" than or "equal" to <value>.

example:

"greater_equal": {
    "<field>": "<value>"
}
less filter

Checks if the value of <field> is "less" than <value>.

example:

"less": {
    "<field>": "<value>"
}
less_equal filter

Checks if the value of <field> is "less" than or "equal" to <value>.

example:

"less_equal": {
    "<field>": "<value>"
}
contain_all filter

Checks if the values of <field> "contain all" of <value>s.

example:

"contain_all": {
    "<field>": ["<value>", ...]
}
contain_some filter

Checks if the values of <field> "contain some" of <value>s.

example:

"contain_some": {
    "<field>": ["<value>", ...]
}
not_contain_any filter

Checks if the values of <field> do "not contain any" of <value>s.

example:

"not_contain_any": {
    "<field>": ["<value>", ...]
}

which is equivalent to:

"not": {
    "contain_some": {
        "<field>": ["<value>", ...]
    }
}
not_contain_all filter

Checks if the values of <field> do "not contain all" of <value>s together. The values of <field> can contain some of <value>s.

example:

"not_contain_all": {
    "<field>": ["<value>", ...]
}

which is equivalent to:

"not": {
    "contain_all": {
        "<field>": ["<value>", ...]
    }
}