Querying Recommendations
You can generic recommendations using the GraphQL orders endpoint. The recommendations offered here don't use sessions so they aren't personalized but still offer enough flexibility to support a multitude of use-cases.
Fetching toplists recommendations
The endpoint can be used to fetch toplist recommendations i.e. best-sellers. Toplists recommendations are either sorted by views or buys.
curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
recos (preview: false, image: VERSION_7_200_200) {
toplist(hours: 168, sort: BUYS, params: {
minProducts: 1
maxProducts: 10
}) {
primary {
name
productId
}
}
}
}
EOF
Fetching random recommendations
The endpoint can be used to fetch random recommendations i.e. previews. Random recommendations are a totally randomized selection of products and often used for testing purposes.
curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
recos (preview: false, image: VERSION_7_200_200) {
random(params: {
minProducts: 1
maxProducts: 10
}) {
primary {
name
productId
}
}
}
}
EOF
Fetching related recommendations
The endpoint can be used to fetch related recommendations i.e. cross-sellers. Cross-sell recommendations allow you fetch related products to a given set of products.
Example: If you were to use this to add recommendations to a product page, the productIds
parameter would be a single-item array containing the product identifiers of the product that is being viewed.
Example: If you were to use this to add recommendations to an order-follow email, the productIds
parameter would be an array containing the product identifiers of the products that were purchased.
curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
recos (preview: false, image: VERSION_7_200_200) {
related(relationship: VIEWED_TOGETHER, productIds: [
"8685560646"
],
params: {
minProducts: 1
maxProducts: 10
}) {
primary {
name
productId
}
}
}
}
EOF
Fetching search recommendations
The endpoint can be used to fetch recommendations related to a search term.
Example: If you were to use this to add recommendations to a search page, the term
parameter would be the entire search term as queries by the user.
Note: This endpoint cannot be used for building auto-complete style integrations.
curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
recos (preview: false, image: VERSION_7_200_200) {
search(term: "shoes",
params: {
minProducts: 1
maxProducts: 10
}) {
primary {
name
productId
}
}
}
}
EOF
Add inclusive or exclusive filters
In case some cases it is desired to filter products by their properties. include
and exclude
fields of primary
should be used to achieve this. The former will filter only the products that match the specified attribute, the later will filter out the products that match the attribute.
include
field expects a type of InputIncludeParams
, whose attributes are
brands: [String]
The list of brand used for inclusion or exclusion
categories: [String]
The list of categories used for inclusion or exclusion
customFields: [InputAttributeParams]
The map of product attributes used for inclusion or exclusion
discounted: Boolean
A boolean indicating whether discounted products should be excluded
fresh: Boolean
A boolean value denoting the inclusion of new products
price: InputPriceParams
The price range used for inclusion
productIds: [String]
The list of product identifiers used for inclusion or exclusion
rating: Float
The minimum rating score for the inclusion
reviews: Int
The minimum amount of reviews for the inclusion
search: String
Search all products containing this text
stock: InputStockParams
The stock level range used for inclusion
tags1: [String]
The first set of tags used for inclusion or exclusion
tags2: [String]
The second set of tags used for inclusion or exclusion
tags3: [String]
The third set of tags used for inclusion or exclusion
exclude
field expect type InputFilterParams
whose attributes are:
brands: [String]
The list of brand used for inclusion or exclusion
categories: [String]
The list of categories used for inclusion or exclusion
customFields: [InputAttributeParams]
The map of product attributes used for inclusion or exclusion
discounted: Boolean
A boolean indicating whether discounted products should be excluded
productIds: [String]
The list of product identifiers used for inclusion or exclusion
search: String
Search all products containing this text
tags1: [String]
The first set of tags used for inclusion or exclusion
tags2: [String]
The second set of tags used for inclusion or exclusion
tags3: [String]
The third set of tags used for inclusion or exclusion
Here is an example of a query including filters
curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
recos (preview: false, image: VERSION_7_200_200) {
toplist(hours: 168, sort: BUYS, params: {
minProducts: 1
maxProducts: 10
include: {
customFields: [
{
attribute: "pattern"
values: ["Solid"]
}
]
discounted: true
}
}) {
primary {
name
productId
}
}
}
}
EOF
Last updated
Was this helpful?