Use the Search & Categories API
Not all of Nosto's functionality is available for pure GraphQL API integrations. The following features require Using the JavaScript Library:
Analytics
Segmentation
A/B testing
Debug toolbar
Both Search and Categories are built on the same technical foundation and use the same API and product data. For simplicity, we will just refer to Search API in the following documentation.
Playground and API reference
Use the Search API Playground to try out search queries and browse API reference.
It provides:
Search request schema - you can see field types and inspect what fields are needed for a search request.
Search result schema - you can see return field types with descriptions.
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!
Authentication Token with API_SEARCH
Role is available on dashboard settings page
Making requests
When integrating Search you have the option to directly access the API, or you can use our existing Search JavaScript library that provides most of the required functionality out of the box.
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
Replace YOUR_ACCOUNT_ID
with your account id retrieved from the Nosto dashboard.
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.
It's possible to get search session data using the JS API:
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).
It's also possible to save session data to cookies on page load:
Using variables
In the search application, you should use variables instead of hardcoded arguments to pass search data. This means that filters, sort, size, and 'from' options should be passed in the 'products' variable. For a full list of available options, please see the reference.
Query
To optimize search speed and reduce network load, select only the necessary data when performing a search 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
To analyze user behavior you need to implement tracking. This can be achieved using our JavaScript library. You need to implement the following methods:
recordSearchSubmit to track search form submissions
Last updated