Implement Search results page

API Requests

Searching

For a basic search, it’s enough to provide accountId, query, and select fields that should be returned. You can control which product attributes to select through products.hits field. See all available fields.

Query

For example, if you want to return only productId and name, the query would be:

query {
  search(accountId: "YOUR_ACCOUNT_ID", query: "green") {
    products {
      hits {
        productId
        name
      }
      total
      size
      from
    }
  }
}

Playground example

Query parameters:

accountId	Nosto account ID
query	search query text

See all query parameters.

Pagination and size

Products offset parameter from is used for pagination functionality.

The default count of documents returned per page is size = 5, you can change it with products.size, and offset of products is controlled with products.from field:

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    query: "green"
    products: { size: 10, from: 10 }
  ) {
    products {
      hits {
        name
      }
      total
      size
      from
    }
  }
}

Playground example

Sorting

By default results are sorted by products relevance score.

To change the sorting, use the sort parameter, where you would specify any indexed field which should be sorted by, and order: asc for ascending and desc for descending.

By default, you should always sort by relevance. Only if the user selects a different sort method, a sorting rule should be used.

Query

query {
    search(
      accountId: "YOUR_ACCOUNT_ID"
      query: "green"
      products: {
        sort: [
          {
            field: "price"
            order: asc
          }
        ]
      }   
  ) {
      products {
        hits {
          productId
          name
          price
        }
      }
    }
  }

Playground example

Faceting

Facets help the user to find products more easily. Faceted navigation is normally found in the sidebar of a website and contains filters only relevant to the current search query. Facets are configured in the Nosto dashboard.

Terms facet

Stats facet

To use facet for a specific field you need to configure it in the Nosto dashboard first.

Terms facet

One of the facet types is type = terms. It returns list if common terms from found documents.

Query

Assume that we have configured facets for customFields.brandname and categories:

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    query: "green"
  ) {
    products {
      facets {
        ... on SearchTermsFacet {
          id
          field
          type
          name
          data {
            value
            count
            selected
          }
        }
      }
    }
  }
}

Playground example

Response

{
  "data": {
    "search": {
      "products": {
        "facets": [
          {
            "id": "345678901abc",
            "field": "categories",
            "type": "terms",
            "name": "Categories",
            "data": [
              {
                "value": "/Shoes",
                "count": 30,
                "selected": false
              },
              {
                "value": "/Shoes/Sportswear",
                "count": 6,
                "selected": false
              }
            ]
          }
        ]
      }
    }
  }
}

Response parameters:

id	internal facet ID, used to select specific facets in query
field	facet field, should be used for filtering
type	facet type, in this case terms
name	user friendly facet name configured in the dashboard
data.value	original facet value, it should be displayed in the user interface
data.count	shows how many products will be returned if you select this facet, it should be displayed in the user interface
data.selected	indicates if there is an active filter on this value

Stats facet

Stats facet returns minimum and maximum number field value from found documents. The most common usage is to render slider filter (e.g. price)/

Query

query {
    search(
      accountId: "YOUR_ACCOUNT_ID"
      query: "green"
  ) {
      products {
        facets {
          ... on SearchStatsFacet {
            id
            field
            type
            name
            min
            max
          }
        }
      }
    }
  }

GraphQL playground example

Response

{
  "data": {
    "search": {
      "products": {
        "facets": [
            {
                "id": "123456789abc",
                "field": "price",
                "type": "stats",
                "name": "Price",
                "min": 0.60,
                "max": 70.99
            }
        ],
      }
    }
  }
}

Response parameters:

name	user friendly facet name configured in the dashboard
terms	facet type, in this case stats
field	facet field, should be used for filtering
id	internal facet ID, used to select specific facets in query
min	minimum field value for documents that match provided query
max	maximum field value for documents that match provided query

Filter

Filtering by terms facet, for example by Adidas, Converse brands:

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    query: "green"
    products: {
      size: 10
      filter: [{ field: "brand", value: ["Adidas", "Converse"] }]
    }
  ) {
    products {
      hits {
        productId
        name
      }
      facets {
        ... on SearchTermsFacet {
          id
          field
          type
          name
          data {
            value
            count
            selected
          }
        }
      }
    }
  }
}

GraphQL playground example

When filtering by multiple same field items, filters will be joined with OR operator and different fields with AND.

If you wish to have more facets, you should configure it in the Nosto dashboard first.

Filtering by stats field, for example by price:

query {
   search(
    accountId: "YOUR_ACCOUNT_ID"
    query: "green"
    products: {
      filter: [
        {
          field: "price",
          range: {lt: "60", gt: "50"}
        }
      ]
    }
  ) {
    products {
      hits {
        productId
        name
      }
      facets {
        ... on SearchStatsFacet {
          id
          field
          type
          name
          min
          max
        }
      }
    }
  }
}

GraphQL playground example

You can sort using these arguments: lt (less than), gt (greater than), lte (less than or equal to), gte (greater than or equal to).

Redirects

Redirects can be used to forward users to special pages depending on their search keywords. For example, users searching for shipping could be forwarded to https://example.com/shipping.html.

For API integrations GraphQL can only return the target URL. The actual browser redirect must be implemented by the merchant.

Query

query {
  search(
    accountId: "YOUR_MERCHANT_ID",
    query: "shipping"
  ) {
    redirect
    products {
      hits {
        name
      }
    }
    keywords {
      hits {
        keyword
      }
    }
  }
}

GraphQL playground example

Response

{
  "data": {
    "search": {
      "redirect": "https://example.com/shipping.html",
      "products": {
        "hits": []
      },
      "keywords": null
    }
  }
}

Session params

For features like personalised results and user segments to function effectively, the search function needs access to the user's session information from the front-end.

It's possible to get search session data using the JS API:

nostojs(api => {
    api.getSearchSessionParams().then(response => {
        console.log(response);
    });
});

The results of this function should be passed to search query sessionParams parameter. In case search is called from backend, it should pass this data to backend (e.g. using form data).

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 = serp:

• recordSearch to track search result interactions like filtering and pagination
• recordSearchClick to track result clicks

Search engine configuration

Nosto Search engine is relevant out of the box and search API can be used without any initial setup. Nosto Dashboard can be used to further tune search engine configuration:

• Searchable Fields - manage which fields are used for search and their priorities,
• Facets - create facets (filtering options) for search results page,
• Ranking and Personalization Ranking and Personalization - manage how results are ranked,
• Synonyms, Redirects, and other search features are also managed through Nosto Dashboard (my.nosto.com).