Prerequisites: This guide assumes that you have created a Search experience. 

Yext Search is a natural language search engine that allows you to search over your Knowledge Graph using natural language. Using the Search API you can query for entities as well as implement modern search UIs that include faceting, query suggest, spellcheck and more. The Search API is designed to be called directly from the client to minimize latency.

The Search API endpoint contains endpoints for both Universal and Vertical Search. Universal search is a single API endpoint that searches across ALL verticals (content types) enabled in the Search experience. The Vertical Search endpoint requires a verticalKey and only searches one specific vertical (e.g. location or FAQ). If you are creating a modern search UI, generally universal search maps to the "All" tab while the other tabs just search a single vertical. You can learn more about Universal and Vertical Search in the Overview of Verticals unit.

The Search API is just for natural language searching and filtering. For indexing content in the Yext platform, check out the Knowledge Graph API.

Step 1: Getting Set Up

Getting Started With Your Search Experience

To get started with the Search API for your own Search experience, you will need the following pieces of information:

• API Key
• Experience Key
• Version (PRODUCTION or STAGING)
• Locale (language)
• Vertical Key (if doing vertical search)
• v (Versioning)

The API Key and the Experience Key can be found under Experience Properties on the "Home" tab of the Search experience. The Vertical Key can be found in the "Additional Vertical Setting" under the verticals configuration tab.

The v parameter (a date in YYYYMMDD format) is designed to give you the freedom to adapt to Yext API changes on your own schedule. When you pass this parameter, any backward-incompatible changes we made to the API after the specified date will not affect the behavior of the request or the content of the response. You will still benefit from any bug fixes or backward-compatible changes we may have made after the date you've specified.

Note: Yext has the ability to make changes that affect previous versions of the API, if necessary.

Getting Started With the Yext Test Account

If you don't have a Search experience set up yet or just want to follow along with the guide, you can use the following parameters:

Sending Requests

For this guide, we will be using Postman to send our API requests. For an introduction to Postman, check out their guide.

Postman is not required - feel free to test the endpoints however you wish: CURL commands, copy pasting the example urls into the browser, your favorite request package, etc. Currently all of the Search API endpoints are GET requests with specified parameters.

Step 2: Autocomplete

Universal Autocomplete

Universal Autocomplete will return a list of suggested queries across all verticals based on the input typed in by a user.

Send a GET request to https://cdn.yextapis.com/v2/accounts/me/answers/autocomplete with the following parameters:

In this example, the user has typed "how" into the search bar:

https://cdn.yextapis.com/v2/accounts/me/answers/autocomplete?v=20210311&api_key=4be28826989e90232722e9bf2769fbf2&experienceKey=cpg-beverages&locale=en&input=how

The autocomplete endpoint returns a structured set of autocomplete options (results), each with the following format:

{
    "value": "how to make vodka martini",
    "matchedSubstrings": [
        {
            "offset": 0,
            "length": 3
        }
    ],
    "queryIntents": []
}

The value is the string to display to the user while the matchedSubstrings can be used for highlighting. queryIntents will indicate whether or not the string has near me intent. One common pattern is to ask for HTML5 geolocation if a user runs a search with near me intent.

For full reference to the Universal Autocomplete API see here.

Vertical Autocomplete

Vertical Autocomplete is very similar to Universal Autocomplete but will only return a list of suggested queries within a specified vertical based on the specified vertical key.

Send a GET request to https://cdn.yextapis.com/v2/accounts/me/answers/vertical/autocomplete with the following parameters:

This will only populate the autocomplete for suggestions in the drinks vertical. The results will follow the same format as Universal Autocomplete. Check out the full response here:

https://cdn.yextapi.com/v2/accounts/me/answers/vertical/autocomplete?v=20210311&api_key=4be28826989e90232722e9bf2769fbf2&experienceKey=cpg-beverages&locale=en&input=how&verticalKey=drinks

For a full reference, see the Vertical Autocomplete API documentation.

Step 3: Query

Universal Query

For full search results across all verticals, use the Universal Query endpoint.

Send a GET request to https://cdn.yextapis.com/v2/accounts/me/answers/query with the following parameters:

In this example, the user has typed "best vodka drink" into the search bar:

https://cdn.yextapis.com/v2/accounts/me/answers/query?v=20210311&api_key=4be28826989e90232722e9bf2769fbf2&experienceKey=cpg-beverages&locale=en&input=best%20vodka%20drink

Modules are returned across all the relevant verticals with the relevant entities for the query in a similar format below:

"modules": [
    {
        "verticalConfigId": "drinks",
        "resultsCount": 2,
        "encodedState": "",
        "results": [
            {
                "data": {
                    "id": "Vodka_Martini",
                    "type": "ce_drink",
                    "name": "Vodka Martini"
                },
                "highlightedFields": {
                    "name": {
                        "value": "Vodka Martini",
                        "matchedSubstrings": [
                            {
                                "offset": 0,
                                "length": 5
                            }
                        ]
                    }
                }
            }
        ]
    }
]

We recommend looping through all the modules and then looping through each result in those modules to show a card per result.

If the direct answer is populated you want to highlight that result at the top of the search results or in some other prominent location. Today there are two types of direct answers - FIELD_VALUE and FEATURED_SNIPPET. FIELD_VALUE comes from the "direct answer" configuration option while FEATURED_SNIPPET comes from the "document search" configuration option. Direct Answers won't show up for every query so make sure to handle cases where it's empty.

For full reference to the Universal Query API see here.

Vertical Query

Vertical Query is similar to the Universal Query endpoint, but only searches within a specified vertical. Vertical Query also has the added benefit of accepting a filters parameter to narrow down search results.

Send a GET request to https://cdn.yextapis.com/v2/accounts/me/answers/vertical/query with the following parameters:

The filter parameter should be provided as a URL-encoded string containing a JSON object. The URL will look like:

https://cdn.yextapis.com/v2/accounts/me/answers/vertical/query?v=20210311&api_key=4be28826989e90232722e9bf2769fbf2&experienceKey=cpg-beverages&locale=en&input=best%20vodka%20drink&filters=%7B%22name%22%3A%7B%22%24eq%22%3A%22Vodka%20Martini%22%7D%7D&verticalKey=drinks

Thanks to the filter, we get one result with the name Vodka Martini:

"response": {
    "businessId": 2533180,
    "queryId": "312e65b9-c6ef-40ea-88ed-c9549debd170",
    "resultsCount": 1,
    "results": [
        {
            "data": {
                "id": "Vodka_Martini",
                "type": "ce_drink",
                "name": "Vodka Martini"
            },
            "highlightedFields": {
                "name": {
                    "value": "Vodka Martini",
                    "matchedSubstrings": [
                        {
                            "offset": 0,
                            "length": 5
                        }
                    ]
                }
            }
        }
    ]
}

For full reference to the Vertical Query API see here.