Step 3: Query

Universal Query

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

Let’s send a GET request to https://lcdn.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 command to narrow down search results.

Let’s 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. Our 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 .