Search returns up to 10000 documents

Due to performance optimization, the search function will calculate the total count up to 10,000. In this case the search page should display a count of 10,000+ to indicate that more than 10,000 products were found.

Filters and sorting operations are executed on all found products, even if there are more than this limit. Therefore, it's still possible to find other products if you filter or sort them. This should not affect the user experience in any way because it's unlikely that someone would actually view more than 10,000 products with a single search.

Products in category listings are in a different order as soon as I deliver results from Nosto API

As soon as you use the results delivered by Nosto API, you will see that the listings in categories have a different order than listings delivered by your native shop-system, even if you didn't set up any merchandising rules. The products are mainly delivered as indexed during the data sync, but there is no defined behaviour for this. We recommend to always set up at least one global rule before going live with Nosto category merchandising to create product listings matching your business strategies.

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

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

Query

Using only category path

Query

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

Query

Other features & implementation

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

Analytics

Nosto Analytics

Playground and API reference

It provides:

1. - you can see field types and inspect what fields are needed for a search request.

2. - you can see return field types with descriptions.

3. Send requests to the search engine and preview the response.

Authentication

In the majority of cases, authentication is not a requirement for using search APIs. However in rare case may need to:

• Access sensitive data- all sensitive data is restricted for public access (e.g. sorting by & returning sales).

• Return all documents - public access require to specify search query, category ID or category path to avoid returning all documents.

Note: Keep your API key secret and do not expose it to the frontend!

Making requests

API endpoint

Search use different API endpoint than other Nosto queries: https://search.nosto.com/v1/graphql

Account ID

All requests require an account ID, which can be found in the top-right corner of the Admin dashboard, under the shop name.

Request example

Response example

Upon a successful request, the API will return a 200 status code response, which includes the search data:

Error handling

Error response

API returns a list of errors with explanations. These errors should be logged internally and not displayed to the end user. Instead, display a general message, such as Search is unavailable at the moment, please try again. This approach ensures that no sensitive information is leaked to the end user.

Partial response

The API may return some errors even when data is returned. This means that some parts of the response may be missing, but you should still display the available data instead of showing an error to the user. These errors should be logged internally for future reference and troubleshooting.

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.

Using variables

Query

Variables

Variables should encompass all dynamic query data because it is the most efficient method to pass data, and data is automatically escaped to prevent injection attacks. Avoid generating dynamic queries, as they can lead to security issues if user input is not properly escaped.

Analytics

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:

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

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:

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:

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.

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).

Autocomplete provides keyword suggestions to assist users in completing their queries, supplemented by a selection of the most relevant products with the ability to see all products on the search results page.

Check out autocomplete's look & feel guidelines.

API Requests

Example

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    query: "green"
    products: { size: 5 },
    keywords: { size: 5 }
  ) {
    products {
      hits {
        productId
        name
      }
      total
    }
    keywords {
      hits {
        keyword
        _redirect
        _highlight {
          keyword
        }
      }
    }
    query
  }
}

Response

{
  "data": {
    "search": {
      "query": "green",
      "products": {
        "hits": [
          {
            "productId": "1",
            "name": "My product"
          }
        ]
        "total": 1
      },
      "keywords": {
        "hits": [
          {
            "keyword": "green",
            "_redirect": "https://example.com/green.html",
            "_highlight": {
              "keyword": "<em>green</em>"
            }
          },
          {
            "keyword": "green energy",
            "_redirect": null,
            "_highlight": {
              "keyword": "<em>green</em> energy"
          }
        ]
      }
    }
  }
}

Highlight

API can return highlights indicating which parts of a keyword match the search query. This HTML can be used to render and emphasize the matching sections during display.

Redirects

Redirects are configured in the search dashboard and can be used to forward users to specific pages depending on what they type into the search field. For example, users searching for "shipping" could be directed to https://example.com/shipping.html.

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

• recordSearch to track users typing in the search field and viewing suggestions

• recordSearchClick to track clicks on autocomplete suggestions

Additionally, see the tracking instructions for search form submissions.

Google Analytics

Each autocomplete product click should be tracked as a search page virtual view to ensure that the Google Analytics search feature displays the correct conversion rate. For example, if you click any product when the typed query is phone it should track a virtual page view with the URL /search?q=phone (adjust the search path and query parameter to match your search page).

Since a product link click would redirect to a new page, to ensure that Google Analytics has time to send the tracking request, it's recommended to save the search query to local storage and track it on page load.