Vertical Search | Hitchhikers

Vertical Search: Autocomplete

Retrieve a list of suggested queries for the selected vertical based on the characters already typed by the user or the most popular queries when no user input is given.

path Parameters

accountId

required

string

query Parameters

v required	string A date in `YYYYMMDD` format.
experienceKey required	string String key that uniquely identifies the Search experience.
verticalKey required	string String key that uniquely identifies the vertical.
locale required	string The locale code of the experience (e.g. `en_GB`).
input	string The partial search term from the user.
version	string The label or version number of the experience configuration to use. Label options are `STAGING` or `PRODUCTION`. `STAGING` uses the Latest version of the configuration. If omitted the `PRODUCTION` label will be used.

Responses

Response samples

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0",
"errors": [ ]
},
"response": {"input": {"value": "yex",
"queryIntents": [ ]
},
"results": [{"value": "Yext Listings",
"matchedSubstrings": [{"offset": 0,
"length": 3
}
]
},
{"value": "Yext Search",
"matchedSubstrings": [{"offset": 0,
"length": 3
}
]
}
]
}
}

Vertical Search: Query

Search for entities within the selected vertical. Vertical query allows for fine tuning of the search using filters, facets and sorts passed in through the API.

In order prevent bot traffic from using Search API Capacity, you must integrate with the Search API from the front end of your application. The Search API's Bot Detection feature requires the API to be called directly from the end-user's web browser. If you must integrate with the Search API via another mechanism, all traffic will be charged against your search capacity and some features of Search Analytics, such as Search Terms and Search Term Clustering may not work.

path Parameters

accountId

required

string

query Parameters

required

string

A date in YYYYMMDD format.

experienceKey

required

string

String key that uniquely identifies the Search experience.

verticalKey

required

string

String key that uniquely identifies the vertical.

locale

required

string

The locale code of the experience (e.g. en_GB). Only returns entities that have an entity profile associated with this locale.

input

string

The search term of the user.

version

string

The label or version number of the experience configuration to use. Label options are STAGING or PRODUCTION. STAGING uses the Latest version of the configuration. If omitted the PRODUCTION label will be used.

location

string

The user's location as a comma separated latitude and longitude (e.g. "40.740957,-73.987565").

locationRadius

string

Radius (in meters) that should be applied to any location filter that does not already have an explicit radius.

session_id

string

UUID used to track session state when cookies are blocked.

limit

integer <= 50

Default: 10

Number of results to return.

offset

integer [ 0 .. 9949 ]

Default: 0

Number of results to skip. Used to move through results.

queryTrigger

string

String value that is logged to analytics denoting the trigger for the query. Options include:

suggest, sent if the query is triggered from a spelling correction.
initialize, sent if the query is being triggered by a default initial search (in other words, the user did not enter query).

context

string

Context is an arbitrary JSON object that is passed to query rules to be used for triggering rules as well as passing data to those rules. This parameter should be provided as a URL-encoded string containing a JSON object.

referrerPageUrl

string

The URL of the webpage that directed to the page this request was made from.

skipSpellCheck

boolean

If true the query will skip spell checking.

filters

string

This parameter represents one or more filtering conditions that are applied to the set of entities that would otherwise be returned. This parameter should be provided as a URL-encoded string containing a JSON object.

For example, if the filter JSON is {"name":{"$eq":"John"}}, then the filters param after URL-encoding will be: filters=%7B%22name%22%3A%7B%22%24eq%22%3A%22John%22%7D%7D

Basic Filter Structure

The filter object at its core consists of a matcher, a field, and an argument.

For example, in the following filter JSON:

{
"name":{
"$eq":"John"
}
}

$eq is the matcher, or filtering operation (equals, in this example),

name is the field being filtered by, and

John is value to be matched against.

Combining Multiple Filters

Multiple filters can be combined to form a conjunction (AND) of disjunctions (ORs) using the combinators $and and $or. For example:

{
"$and": [
{
"$or": [
{
"firstName": {
"$eq": "Jane"
}
},
{
"firstName": {
"$eq": "John"
}
}
]
},
{
"lastName": {
"$eq": "Smith"
}
}
]
}

Any filter that is the only item in its respective combinator may omit the combinator as is done with the lastName above.

Filter Negation

Certain filter types may be negated. For example:

{
"$not": {
"name": {
"$eq": "John"
}
}
}

This can also be written more simply with a ! in the $eq parameter. The following filter would have the same effect:

{
"name":{
"!$eq":"John"
}
}

TEXT

The TEXT filter type is supported for text fields. (e.g., name, countryCode)

Matcher Details

$eq (equals)

{
"countryCode":{
"$eq":"US"
}
},
{
"countryCode":{
"!$eq":"US"
}
}

Supports negation. Case insensitive.

BOOLEAN

The BOOLEAN filter type is supported for boolean fields and Yes / No custom fields.

Matcher	Details
$eq	`{ "isFreeEvent": { "$eq": true } }` For booleans, the filter takes a boolean value, not a string. Supports negation.

OPTION

The OPTION filter type is supported for option custom fields and fields that have a predetermined list of valid values.

*e.g., eventStatus, gender, SINGLE_OPTION and MULTI_OPTION types of custom fields.*

Matcher	Details
$eq	Matching is case insensitive and insensitive to consecutive whitespace. e.g., "XYZ 123" matches "xyz 123" `{ "eventStatus": { "$eq": "SCHEDULED" } }`

INTEGER, FLOAT, DATE, DATETIME, and TIME

These filter types are strictly ordered -- therefore, they support the following matchers:

Equals
Less Than / Less Than or Equal To
Greater Than / Greater Than or Equal To

Matcher	Details
$eq	Equals `{ "ageRange.maxValue": { "$eq": "80" } }` Supports negation.
$lt	Less than `{ "time.start": { "$lt": "2018-08-28T05:56" } }`
$gt	Greater than `{ "ageRange.maxValue": { "$gt": "50" } }`
$le	Less than or equal to `{ "ageRange.maxValue": { "$le": "40" } }`
$ge	Greater than or equal to `{ "time.end": { "$ge": "2018-08-28T05:56" } }`
$between	An array that must contain exactly two elements with which the result is between. `{ "time.end": { "$between": ["2018-08-28T05:56", "2018-08-29T05:56"] } }`
Combinations	In addition to between, it is possible to combine multiple matchers for a result similar to an "and" operation: `{ "ageRange.maxValue" : { "$gt" : 10, "$lt": 20 } }`

facetFilters

string

This parameter represents the state of the currently checked facet options. This parameter should be provided as a URL-encoded string containing a JSON object.

The JSON object contains a key for each facet category that has a checked facet option. The value for each of these keys is an array of Filter objects that describe the filter that is applied by the facet option.

At the moment, facet options only support $eq.

For example, if Engineering was checked under the Category facet and Chicago and New York are checked under the Job Location facet, the facetFilters would look like:

{
"c_jobCategory": [
{
"c_jobCategory": {
"$eq": "Engineering"
}
}
],
"c_jobLocation": [
{
"c_jobLocation": {
"$eq": "Chicago"
}
},
{
"c_jobLocation": {
"$eq": "New York"
}
}
]
}

retrieveFacets

boolean

Whether facets should be computed for this vertical query.

sortBys

string

This parameter overrides the sort options that are configured on the experience configuration. This parameter should be provided as a URL-encoded string containing a JSON array.

The input is a JSON array containing each of the sort options in the order in which they should be applied.

Each sort options must contain a type

Type	Details
RELEVANCE	Sorts based on relevance according to the algorithm and, when relevant, location bias
ENTITY_DISTANCE	Sorts based on entity distance alone
FIELD	sorts based on a field with the direction specified

If the type is FIELD the sort options must also specify field which is the api name of the field to sort on.

Finally, if the type is FIELD the sort options must also specify the direction.

Direction	Details
ASC	Sorts in ascending order. For numbers this is low to high. For text this is alphabetical. For dates this is chronological order.
DESC	Sorts in ascending order. For numbers this is high to low. For text this is reverse alphabetical. For dates this is reverse chronological order.

Examples

[
{
"type": "FIELD",
"direction": "ASC",
"field": "startDate"
},
{
"type": "RELEVANCE",
"direction": "ASC"
}
]

ignoreQueryRules

boolean

When set to true, ignores any Query Rules that would otherwise affect the results. Defaults to false.

queryId

string

UUID of the query; recommended when moving through results, to associate multiple requests to the same query.

source

string

Indicates where the query is coming from (e.g. "HOME_HEADER" or "TICKET_FORM"). Can be used in Analytics reports via the Integration Source dimension. Defaults to "STANDARD".

jsLibVersion

string

The version of the Search UI used for this request. Deprecated.

Responses

Response samples

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"businessId": 0,
"queryId": "string",
"resultsCount": 0,
"results": [{"data": { },
"highlightedFields": { },
"distance": 0,
"distanceFromFilter": 0
}
],
"appliedQueryFilters": [{"displayKey": "string",
"displayValue": "string",
"filter": "c_exampleFieldId: { $eq\": \"Search\" }\n",
"type": "FIELD_VALUE",
"details": { }
}
],
"facets": [{"fieldId": "string",
"displayName": "string",
"options": [{"displayName": "string",
"count": 0,
"isSelected": true,
"filter": "c_exampleFieldId: { $eq\": \"Search\" }\n"
}
]
}
],
"searchIntents": ["string"
],
"source": "KNOWLEDGE_MANAGER",
"directAnswer": {"type": "string",
"answer": { },
"relatedItem": {"verticalConfigId": "string",
"data": { }
}
},
"alternativeVerticals": {"modules": [{"verticalConfigId": "string",
"resultCount": 0,
"encodedState": "string",
"results": [{"data": { },
"highlightedFields": { },
"distance": 0,
"distanceFromFilter": 0
}
],
"appliedQueryFilters": [{"displayKey": "string",
"displayValue": "string",
"filter": "c_exampleFieldId: { $eq\": \"Search\" }\n",
"type": "FIELD_VALUE",
"details": { }
}
]
}
],
"failedVerticals": [{"verticalConfigId": "string",
"errorType": "TIMEOUT",
"details": {"responseCode": 0,
"description": "string"
},
"queryDurationMillis": 0
}
]
},
"spellCheck": {"originalQuery": "string",
"correctedQuery": {"value": "string",
"matchedSubstrings": [{"offsets": 0,
"length": 0
}
]
},
"type": "SUGGEST"
},
"locationBias": {"latitude": 41.7828,
"longitude": -87.8781,
"locationDisplayName": "Countryside, Illinois, United States",
"accuracy": "IP"
},
"allResultsForVertical": {"businessId": 0,
"queryId": "string",
"resultsCount": 0,
"results": [{"data": { },
"highlightedFields": { },
"distance": 0,
"distanceFromFilter": 0
}
],
"facets": [{"fieldId": "string",
"displayName": "string",
"options": [{"displayName": "string",
"count": 0,
"isSelected": true,
"filter": "c_exampleFieldId: { $eq\": \"Search\" }\n"
}
]
}
],
"searchIntents": ["string"
]
}
}
}

Vertical Search: Filter Search

Retrieve a list of potential filters that match the user's input up to that point. This differs from query suggest by only returning the names of filters that can be searched rather than the broader corpus of suggested queries.

path Parameters

accountId

required

string

query Parameters

required

string

A date in YYYYMMDD format.

experienceKey

required

string

String key that uniquely identifies the Search experience.

verticalKey

required

string

String key that uniquely identifies the vertical to scope the filter search request to.

locale

required

string

The locale code of the experience (e.g. en_GB).

input

required

string

The search term of the user.

search_parameters

required

string

This parameter represents the parameters that should be used for filter search. This parameter should be provided as a URL-encoded string containing a JSON object.

Filter search uses the user's input string to find a set of existing filters that match the user's input query for the fields provided in the parameters.

The JSON object must have a fields property made up of a list of FilterField objects that have the following properties:

Property	Details
fieldId	The api name of the field.
entityTypeId	The api name for the entity type the filter belongs to.
shouldFetchEntities	Optional boolean. If true, entities matching each filter will be returned inline with the filter.

Additionally, there is an optional boolean property sectioned. If set to true, the matching filters will be returned in a separate section per field. By default, they are all returned in the same section.

version

string

excluded

string

This parameter represents any values which should not be returned. This parameter should be provided as a URL-encoded string containing a JSON array, where each entry of the array is a JSON object representing a field and an excluded value for that field. For example:

[
{
"name": {
"$eq": "John"
}
},
{
"c_jobCategory": {
"$eq": "Engineering"
}
}
]

Responses

Response samples

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"businessId": 0,
"sections": [{"label": "string",
"results": [{"key": "string",
"value": "string",
"filter": "c_exampleFieldId: { $eq\": \"Search\" }\n",
"matchedSubstrings": [{"offset": 0,
"length": 0
}
],
"relatedItem": { }
}
]
}
],
"failedVerticals": [{"verticalConfigId": "string",
"errorType": "TIMEOUT",
"details": {"responseCode": 0,
"description": "string"
},
"queryDurationMillis": 0
}
],
"queryId": "string"
}
}