Search Query API Responses | Yext Hitchhikers Platform

This reference doc outlines all properties returned in API responses for search queries and is meant to serve as a resource when using API responses to debug backend search issues.

For details on the query parameters and more examples of API requests, check out the Search API documentation for a universal search query and vertical search query .

Example API Request - No Results on Universal Search

You should always see something returned in the API request, even if the search returned no results. Here is an example:

// Full API Reponse for Universal Search - No Results
"response": {
  "businessId": 3701021,
  "modules": [],
  "failedVerticals": [],
  "queryId": "018508b7-c43b-d700-590f-52b262c7d64d",
  "searchIntents": [],
  "locationBias": {
    "latitude": 40.7306,
    "longitude": -73.9866,
    "locationDisplayName": "New York City, New York, United States",
    "accuracy": "IP"
  }
}

Note

If you ever see an error when loading the API request (specifically a 500 error), then there could be a Yext Live API outage. Check the Yext Trust Site for any outages.

Top-Level Properties

Here are the top-level properties of the API response found in the response object. These are not specific to the query results, and instead contain general information about the request. Take a look at the above request for an example.

All top-level properties for universal searches are included in this table. Vertical searches have these properties and additional result-level properties that are listed in the next section.

Attribute	Description
`businessID`	The business ID of the experience
`modules` (Console) / `verticalResults` (Platform) (universal search only)	Each object in the array represents a vertical in the universal search response. These properties are equivalent but use different names whether you view the API response in the console or in the platform.
`failedVerticals` (universal search only)	If this array is not empty, it indicates there is an error and you should submit a ticket to Engineering.
`queryID`	The unique identifier for that query.
`directAnswer` (optional)	If a Direct Answer is returned in the results, the API response will include this object with details on the direct answer returned, including type (`FEATURED_SNIPPET` or `FIELD_VALUE`) and content pulled from the related entity.
`searchIntents`	The vertical intent defined for that vertical.
`locationBias`	The location of the searcher. This is often inferred by the user’s IP address. In the above example, we know that location-centric results will be biased to the user’s current device location, which is New York City, New York, United States of America.
`allResultsForVertical` (only for no results on vertical search)	If the vertical is configured to display all results when there are no results , this object will display the results-level properties discussed in the next section.
`alternativeVerticals` (only for no results on vertical search)	If there are no results for a vertical search, results from other verticals will display and this object will show the results-level properties discussed in the next section.

Note

You can spoof your location in the API Request by adding &location=lat,long to the request URL.

Result-Level Properties

This section covers properties specific to the results of a query. These can contain entity data, or a record of which algorithm(s) were applied and how. You can quick-find these attributes by performing a simple cmd/ctrl + F.

For universal search, these properties live in the modules array. Each object in the array represents a vertical in the Universal Search response. For vertical search, they live directly in the response object (in addition to the top-level properties listed above).

Attribute	Description
`verticalConfigId` (Console) / `verticalKey` (Platform)	The vertical key of the current result set.
`resultsCount`	The number of results returned for that search
`results`	The result set returned for each vertical. Each entity is represented by an object in this array. The API response viewed from the console will only return the number of results up to the universal or vertical limit, even if that is lower than the `resultsCount`. The API response viewed from the platform will return up to 10 results per vertical.
`results.[].data` (Console) / `results.[].rawData` (Platform)	Contains all data pulled in by the API for each result returned, showing each field and field value.
`results.[*].highlightedFields`	Contains any Text Search, Phrase Match, or Document Search matches with the query, to help determine why the result was returned. The object includes the field name (object key), `value` of the field, and offset position and length of the text search or phrase match `matchedSubstrings`.
`appliedQueryFilters`	Any NLP Filters that were applied, including the field (`displayKey`) and field value (`displayValue`) it matched on.
`facets`	Any facet options that appeared with the query results, even if they weren’t applied. If any were applied, that would also be indicated here.
`source`	The source of the content for this vertical. Options include `YEXT` (Content) or a third-party vertical. Built-in third-party verticals include Google Programmable Search Engine (`GOOGLE_CSE`), Bing (`BING_CSE`), Zendesk (`ZENDESK`), and Algolia (`ALGOLIA`).

Back

< Search Log Details Page

Experience Training Table >

Feedback

<% elem.innerText %>