loading

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

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

experienceKey
required
string

String key that uniquely identifies the answers 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 filter param after URL-encoding will be: filter=%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"
  }
]

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

locale
required
string

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

verticalKey
string

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

excluded
string

JSON array containing the IDs of all filters that should be excluded from filter search results (if it has already been returned and selected). This parameter should be provided as a URL-encoded string containing a JSON array.

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 parameters are made up of a list of FilterField objects that have the following properties:

Property Details
field The api name of the field.
entityTypeId The numeric entityTypeId 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 parameter 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.

input
required
string

The search term of the user.

Responses

Response samples

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