1 of 8

Using Queries

The query methods allow you to fetch basic recommender data and does not require any sessions. Query operations are light and do not give you the benefit of personalization but can be used to fulfill simple use cases e.g. an in-store display that always shows the top 10 viewed products.

_The given example simply fetches products related to a given search term aliased as q_related and also fetches the most viewed products within the last week.

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) {
    hot_now: toplist(hours: 168, sort: VIEWS, params: {
      minProducts: 1
      maxProducts: 10
    }) {
      primary {
        name
        productId
      }
    }
    q_related: search(term: "black", params: {
      minProducts: 1
      maxProducts: 10
    }) {
      primary {
        name
        productId
      }
    }
  }
}
EOF

Querying Products

List Products

Querying products gives access to Nosto's product catalogues current state. It can be useful for backend integration and verification purposes. It is not meant for online use purposes as it doesn't include any concepts related to user sessions or attribution, for those refer to GraphQL For Headless

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  products(
    limit: 5
    offset: 0
    sort: {field: PRICE, reverse:true},
    filter: {categories: "shoes"}
  ) {
    products {
      productId
      url
      price
      categories
    }
  }
}
EOF

The maximum number of products that can be paged over is capped at 10000. If you need to get around this limitation, we recommend adding more restrictive filters to narrow down the result set.

Query by Product ID

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  product(id: "5358") {
    productId
    name
    url
    price
    listPrice
    imageUrl
    attributes {
      key
      value
    }
    skus {
      name
      price
      listPrice
      availability
      imageUrl
      url
    }
  }
}
EOF

Querying Identities

You can query identities using the GraphQL Identities endpoint. An "identity" is the personal information associated with an email address.

So long as you are able to specify the email address, you will be able to query the identity, its associated customer affinity and the personalized recommendations for that identity.

What can identity attributes be used for?

Querying Orders

You can query orders using the GraphQL orders endpoint. So long as you are able to specify the order number or an external order reference, you will be able to query the order.

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.

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.

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.

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.

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

exclude field expect type InputFilterParams whose attributes are:

Here is an example of a query including filters

Querying Segments

You can query all the configured segments using the GraphQL Segments endpoint. You are able to query all the names and identifiers of the segments.

Sample Output

Querying Search

Search GraphQL API uses different API endpoint. For more information see:

Querying Category Merchandising Products (CM 1.0)

This documentation is only for the implementation of CM 1.0 and most likely this doc shouldn't be used anymore. If you'd like to implement CM 2.0, please check this . If you're not sure which version you'd like to implement, please contact your technical solutions manager or our support.

Nosto's category merchandising APIs are meant to be used for resorting your existing product listing pages. It has support for listing the products in the order defined within Nosto for different categories, including paging and filtering support. It doesn't support taking over the product listing pages fully as it doesn't include support for creating category specific filters and calculating their facet counts. The expected implementation leveraging these APIs would keep on using their current solution for building most of the product list pages, but swap the shown products with the information retrieved from this APIs results.

You can query using the query below:

Session Lookup

Attribution

Automatic Attribution

Setting the addAttributionParameters parameter to true, causes attribution parameters to be automatically rendered in product URLs. For example, the url https://example.com/product becomes https://example.com/product?nosto_source=cmp&nosto=5e5e09f060b232790cbbccbf. These parameters allow our client script to track the performance of Category Merchandising results.

Manual Attribution

If you wish to handle attribution parameters manually, the addAttributionParameters parameter can either be set to false or can be omitted.

Product views resulting from clicking products of a category listing need to contain the required attribution parameters:

type: VIEWED_PRODUCT
target: (product id)
ref: (resultId from the category merchandising response)
refType: CATEGORY_MERCHANDISING

For example, given the following category merchandising response:

If a customer clicks on Cool Kicks, the following GraphQL query should be sent to fetch the product's details and to attribute the product view to the category merchandising result:

Event handling

Graphql calls using Category Merchandising methods are treated as a category view by default. This behavior can be changed by including skipVCEvent: true into the graphql request. All product URLs on a category page must be appended with #nosto\_cmp fragment. An example of such a product URL would be www.test-store.com/product1#nosto\_cmp where #nosto\_cmp is the added fragment.

Pagination

The batchToken can be used the next batch of results. This is useful if you only wish to fetch the first 10 products when there may be thousands of results. To fetch the next batch, use the batchToken in the next query like in the example below:

If you wish to skip the first number of pages, you can use the skipPages parameter instead of the batchToken. A page size is calculated from the maxProducts parameter.

Filtering Results

Querying Recommendations

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.

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

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.

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

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

Querying Category Merchandising Products (CM 1.0)

You can query using the query below:

Session Lookup

In order to be able to provide personalized results, we will need to look up a session either by id or by reference. You read more about managing sessions on our wiki page.

Attribution

Automatic Attribution

Manual Attribution

If you wish to handle attribution parameters manually, the addAttributionParameters parameter can either be set to false or can be omitted.

Product views resulting from clicking products of a category listing need to contain the required attribution parameters:

type: VIEWED_PRODUCT
target: (product id)
ref: (resultId from the category merchandising response)
refType: CATEGORY_MERCHANDISING

For example, given the following category merchandising response:

{
  "data": {
    "updateSession": {
      "recos": {
        "category": {
          "resultId": "623473861055d80027efe482",
          "primary": [{
            "productId": "9497180547",
            "name": "Cool Kicks",
            "url": "https://example.com/products/cool-kicks"
          }]
        }
      }
    }
  }
}

If a customer clicks on Cool Kicks, the following GraphQL query should be sent to fetch the product's details and to attribute the product view to the category merchandising result:

mutation($sessionId: String!) {
  updateSession(by: BY_CID, id: $sessionId, params: {
    event: {
      type: VIEWED_PRODUCT
      target: "9497180547"
      ref: "623473861055d80027efe482"
      refType: CATEGORY_MERCHANDISING
    }
  }) {
    primary {
      productId
      url
      name
      description
      priceText
    }
  }
}

Event handling

Pagination

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  session(by: BY_CID, id: $customerId) {
    id
    recos(
      preview: false,
      image: VERSION_ORIGINAL,
      addAttributionParameters: true) {
      category(
        category: $categoryName,
        minProducts: 1,
        maxProducts: 10,
        batchToken: "n200MjA2NDc0OTUyNzg1+z/wAAAAAAAA/w=="
      ) {
        primary {
          productId
          url
        }
        batchToken
        totalPrimaryCount
        resultId
      }
    }
  }
}
EOF

If you wish to skip the first number of pages, you can use the skipPages parameter instead of the batchToken. A page size is calculated from the maxProducts parameter.

Filtering Results

Results can be filtered by specifying the include and exclude parameters. You can explore more parameters in the

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  session(by: BY_CID, id: $customerId) {
    id
    recos(
      preview: false,
      image: VERSION_ORIGINAL,
      addAttributionParameters: true) {
      category(
        category: $categoryName,
        minProducts: 1,
        maxProducts: 10,
        include: {
          customFields: [{
            attribute: "color",
            values: ["white"]
          }]
        }
        exclude: {
          discounted: true
        }
      ) {
        primary {
          productId
          url
        }
        batchToken
        totalPrimaryCount
        resultId
      }
    }
  }
}
EOF

Using Queries

Querying Products

List Products

Query by Product ID

Querying Identities

What can identity attributes be used for?

Querying Orders

Querying Recommendations

Fetching toplists recommendations

Fetching random recommendations

Fetching related recommendations

Fetching search recommendations

Add inclusive or exclusive filters

Querying Segments

Sample Output

Querying Search

Querying Category Merchandising Products (CM 1.0)

Session Lookup

Attribution

Automatic Attribution

Manual Attribution

Event handling

Pagination

Filtering Results

Using Queries

Querying Products

List Products

Query by Product ID

Querying Identities

What can identity attributes be used for?

Querying Segments

Sample Output

Querying Orders

Querying Recommendations

Fetching toplists recommendations

Fetching random recommendations

Fetching related recommendations

Fetching search recommendations

Add inclusive or exclusive filters

Querying Search

Querying Category Merchandising Products (CM 1.0)

Session Lookup

Attribution

Automatic Attribution

Manual Attribution

Event handling

Pagination

Filtering Results