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.

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:

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

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
    }
  }
}

Price Formatting and Currency Display

You can request specific currency formatting settings for prices returned in the search results. This is done by specifying the currencyFormat parameter within the products input. The actual formatting details (like currency symbol, placement, decimal places) are then returned in the priceFormat field within the products object of the response.

Query

To select which pre-configured currency settings to retrieve, include the currencyFormat parameter within the products input. Additionally, ensure you request the priceFormat field in your query to receive these details.

query (
  $accountId: String,
  $products: InputSearchProducts,
) {
   search(
    accountId: $accountId
    products: $products
  ) {
     products {
      # This field will contain the details of the selected currency format
      priceFormat {
        currencySymbol
        placement
        decimalPlaces
        decimalSeparator
        thousandSeparator
      }
    }
  }
}

Variables Example:

{
  "accountId": "shopify-55872454679-538837015-fi",
  "products": {
    "currencyFormat": "EUR"
  }
}

Behavior and Error Handling:

If currencyFormat is not provided in the products input, the default currency format configured for the account will be used for the priceFormat field.
If currencyFormat is provided but corresponds to a currency for which no settings are configured, an error will be returned.
If currencyFormat is not provided and no default currency format exists for the account, an error will be returned.

Response Example:

{
  "data": {
    "search": {
      "products": {
        "priceFormat": {
          "currencySymbol": "€",
          "placement": "after",
          "decimalPlaces": 2,
          "decimalSeparator": ",",
          "thousandSeparator": " "
        }
      }
    }
  }
}

`priceFormat` Response Parameters:

These parameters describe how the prices should be formatted on the frontend based on the selected currencyFormat.

Name

Description

currencySymbol

The symbol for the currency (e.g., "$", "€").

placement

Indicates where the currency symbol is placed relative to the price ("before" or "after").

decimalPlaces

The number of decimal places to display for the price.

decimalSeparator

The character used to separate the decimal part of the price (e.g., ".", ",").

thousandSeparator

The character used to separate thousands in the price (e.g., ",", " ").

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

PreviousUse the Search & Categories API NextImplement Autocomplete

Last updated 7 days ago

Was this helpful?

API Requests

Searching

Query

Query parameters:

Pagination and size

Query

Sorting

Query

Faceting

Terms facet

Query

Response

Response parameters:

Stats facet

Query

Response

Response parameters:

Filter

Query

Redirects

Query

Response

Price Formatting and Currency Display

Query

Behavior and Error Handling:

Response Example:

priceFormat Response Parameters:

Session params

Analytics

Nosto Analytics

Search engine configuration

`priceFormat` Response Parameters: