Integrating using REST APIs
One way of integrating your website or application with Search is to use APIs.
The other way of integrating with Search is to use the JavaScript SDK.
Search offers the following APIs for integration:
-
Search and Recommendation - Use the Search and Recommendation API to create search experiences for your customers. You can get search results, filter, sort, personalize, suggest content, and more.
When you work with the Search and Recommendation API, refer to the API reference for a detailed data model and descriptions of the objects and keys.
-
Events - Use the Events API to capture and report on visitor actions or other events on your website or mobile app. Events are one of the important signals used by the AI core of Search.
When you work with the Events API, refer to the API reference for the detailed data model and descriptions of all objects and keys.
-
Authentication - Use the authentication API to get a key or token that that you can use to authenticate requests to Search. This applies only if you do not have a subdomain.
Typical API integration flow
Here is a typical workflow that you go through when you integrate with Search using APIs:
-
If you do not have a subdomain, get an API key or access token. If you have a subdomain, you do not need any authentication.
-
Plan how to create an anonymous unique identifier for each visitor.
While this is not strictly required, we strongly recommend that you create and send an anonymous identifier for each visitor to tie requests to a visitor across multiple sessions. This allows us to serve personalized search results and generate analytics.
-
Gather the following information from an administrator:
-
Which widgets and pages you need to create the desired search experience. For example, the business requirement might be to show a full-page search on your company's home page but only a preview search on the page for each vertical.
-
Which content needs to be made available for each search experience. All of your domain's indexed content might not need to be available for all search experiences. For example, the full-page search on your company's home page might need to search all available content. However, the preview search on a vertical's page might need to only search content relevant to that vertical.
-
Which features, like facets, sorting, and others, are required for each search experience and how these features are configured.
NoteWhile an administrator configures many features in Search, you might need to pass some settings at runtime.
-
-
Create test requests to the Search and Recommendation API. At this time, also study the response and identify which parts you'll use to create search experiences.
-
In your application, add code to create requests to the Search and Recommendation API. Also, add code to grab the parts of the response you'll need to create search experiences.
Study the use cases and look at the data model in the API reference to create your request.
-
Add code to send requests to the Events API. There are many events that are possible based on the actions your visitors take.
Study the use cases and look at the data model in the API reference to create your request.
-
Deploy your website or app.
After your website or app is deployed, you can monitor events and make adjustments to the requests you send to the Events API.
NoteWe recommend that you also disable any other search that your application might have. This is to reduce the stress of many crawlers crawling your content.
We've created a walkthrough with sample requests to handle the use case of a visitor landing on a search page, searching, selecting a facet, filtering, and then clicking a content item.