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.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

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
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). Only returns entities that have an entity profile associated with this locale.

input
string

The search term of the user.

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": {
    },
  • "response": {
    }
}

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
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 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.

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": {
    },
  • "response": {
    }
}
Feedback