Implement Category pages

Nosto provides functionality to retrieve all products for a specific category. This is useful when you want to implement category merchandising using the same API as for Search.

API Requests

Using category ID and category path

Using the category ID is only fully supported for Shopify merchants. Others should use the category path instead to benefit from full functionality.

Provide the categoryId API parameter to fetch all products associated with that category. Additionally categoryPath should be provided for better analytics data.

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    products: {
      categoryId: "123456789",
      categoryPath: "Pants"
    }
  ) {
    products {
      hits {
        productId
        name
        url
        imageUrl
        price
      }
      total
      size
    }
  }
}

Product fields that can be requested in the hits object are documented here. All indexed fields are accessible via the API.

Using only category path

Provide the categoryPath API parameter to fetch all products associated with that category. This parameter is the same as the categories product field.

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    products: {
      categoryPath: "Pants"
    }
  ) {
    products {
      hits {
        productId
        name
        url
        imageUrl
        price
      }
      total
      size
    }
  }
}

Product fields that can be requested in the hits object are documented here. All indexed fields are accessible via the API.

Child category handling

Depending on your configuration, fetching a parent category will also include products from the child categories. For example, fetching products for the category Pants would also include products from the categories Pants -> Shorts and Pants -> Khakis.

This is an admin-only setting. Please contact your Nosto representative to adjust this setting.

Using custom filters

In some rare cases categoryId or categoryPath is not enough. In these cases custom filters can be used to build any query for category & landing pages.

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    products: {
      preFilter: [
        {
          field: "productId",
          value: [
            "2276",
            "2274"
          ]
        }
      ],
    }
  ) {
    products {
      hits {
        productId
        name
      }
      total
      size
    }
  }
}

Other features & implementation

The category page shares a lot of similarities with the search page, so please refer to the search page documentation:

Implement Search results page

Analytics

Nosto Analytics

To analyze user behavior you need to implement tracking. This can be achieved using our JavaScript library. You need to implement the following methods with type = category:

• recordSearch to track category page visits
• recordSearchClick to track clicks on category results