Verticals | Yext Hitchhikers Platform

A vertical is a class of results that are grouped together for a search. It is often synonymous with an entity type, though you can choose to have multiple entity types in a given vertical if you’d like those results to be combined. When users run a vertical search, they are only running a search on that one vertical.

Search Configuration Schema

Within the Search configuration, verticals is a top-level object that defines the configuration settings for each vertical. Within verticals, each vertical is defined as a separate object that uses the vertical key as the key and has the following available top-level fields.

View where verticals fits into the configuration in the Search Config Properties - Top Level reference doc. Find more detail about these properties below.

This table only displays properties for the source is YEXT, i.e. when the vertical uses content from the Yext platform. If you are using a third-party vertical, refer to the Search Config - Third Party Verticals reference doc for the schema.

Top-Level JSON

The JSON below is for demonstrative purposes only to show the structure of the verticals object through the top-level properties of an individual vertical. Find more detail about each object below.

  "verticals": {
    "restaurants": {
      "authorization": {},
      "directAnswers": {},
      "displayFields": [],
      "dynamicRerank": {},
      "entityTypes": [],
      "facets": {},
      "facetOrder": [],
      "minLocationRadius": 5000,
      "name": "Restaurants",
      "nlpFilterOrder": [],
      "savedSearchId": "112002255",
      "searchableFields": {},
      "semanticThreshold": {},
      "semanticVerticalBias": 0.2,
      "semanticVerticalIntents": [],
      "semanticVerticalRankingPriorityFields": [],
      "semanticVerticalThreshold": 0.2,
      "sortBys": [],
      "source": "YEXT"
    }
  },

Authorization

Set up Authorized Search to authenticate users so that only the information the user has access to view will appear in search results. You can authenticate users using either Yext Auth or any existing authentication system you may have already configured.

To learn how to set up authorized search using Yext Auth, check out the Set up a Yext Authenticated Site and an Authorized Search Experience guide.

To learn how to set up authorized search using external authentication, check out the Set up Search with External Authorization guide.

In the authorization object, set the type based on what authorization you’re using.

Direct Answers

Advanced Search Tier Feature

Direct answers are only available on the Advanced Search tier. Check out the Search Tiers reference doc to learn more about the features that are available in each tier.

Direct answers are meant to directly answer a user’s question by extracting information from results. There are two types of direct answers: Field Value Direct Answers come from structured data and Featured Snippet Direct Answers come from unstructured data. Check out the Direct Answers unit for more details.

Within directAnswers, the configuration needed to set up each type of direct answer is below.

Featured Snippet Direct Answer

Featured snippets extract answers to users’ questions from any unstructured fields for which the searchable field type document search is activated (learn more in the Searchable and Display Fields unit). Since these types of fields tend to contain long form content, featured snippets will extract out the snippet that best responds to the query.

For example, this Help Articles vertical has the prediction mode for featured snippets set to APPROVE_ONLY, so only featured snippets approved in Experience Training will surface.

    "help_articles": {
      "directAnswers": {
        "featuredSnippets": {
          "predictionMode": "APPROVE_ONLY"
        }
      }
    }

Field Value Direct Answer

Field value direct answers respond to user questions directly using structured Content fields you designate as eligible. The entire value of the eligible field is returned as the direct answer.

For example, this Restaurants vertical would return mainPhone as a direct answer with the prediction mode CLASSIFIER.

    "restaurants": {
      "directAnswers": {
        "fieldValues": {
          "eligibleFields": [
            "mainPhone"
          ],
          "predictionMode": "CLASSIFIER"
        }
      }
    }

Display Fields

For each vertical, you can use the displayFields property to specify the entity profile fields that are returned as part of the Search API response. If you don’t include the displayFields property (default), the Search API response returns all fields on the result entity, but not any fields of related entities. If you do include the displayFields property, Search will only return the fields that you provide in this property, even if they are on the result entity.

You can only display fields on the frontend if they are passed to the frontend by the backend via the Search API response, so display fields are required if you want to display a field value from a related entity of a result in the frontend.

You need to be precise when specifying display fields, particularly for linked entities. If there is a particular subfield you are looking to use, specify that subfield exactly instead of the parent field. For example, if you want to display a doctor’s specialties on their result card, add c_relatedSpecialties.name to display fields, not c_relatedSpecialties.

Note

Note you can’t include both the top-level field and subfields of that parent field in the same display fields stream. In this example, you can’t have both c_relatedSpecialties and c_relatedSpecialties.name in the list of display fields.

Note that Search API responses return all display fields that ever exist on any version of the experience. For example, if version 45 has the “description” field as a display field, but the most recent version 49 does not, the Search API response would still return “description”.

For example, in a doctors vertical, each doctor is related to specialty entities that have lists of related conditions and treatments. You want to display the names of those specialties, conditions, and treatment. Here is an example of a displayFields property that you might set up to display all of those attributes:

    "doctors": {
      "displayFields": [
        "name",
        "c_specialty.name",
        "c_specialty.c_relatedConditions.name",
        "c_specialty.c_relatedTreatments.name"
      ]
    }

Check out the Searchable and Display Fields unit for more details.

Dynamic Rerank

Advanced Search Tier Feature

Dynamic reranking is only available on the Advanced Search tier. Check out the Search Tiers reference doc to learn more about the features that are available in each tier.

Dynamic reranking uses machine learning to rerank results and answers based on user engagement data. If you turn on dynamic reranking for a vertical, the algorithm gradually learns to optimize the order of results based on the number of clicks. Check out the Sorting (Backend) unit for more details.

The dynamicRerank object just takes one property.

If you turn on dynamic reranking for the FAQs vertical, here is what the JSON configuration would look like:

    "faqs": {
      "dynamicRerank": {
        "target": "CLICKS"
      },
    }

Entity Types

Specify the entity types to map to each vertical in the entityTypes array.

For example, in the JSON configuration below, the Events vertical uses the events entity type and the Locations vertical uses both the locations and ATMs entity types.

  "verticals": {
    "events": {
      "entityTypes": [
        "event"
      ],
    },
    "locations": {
      "entityTypes": [
        "location",
        "atm"
      ],
    }
  }

Facets

Facets allow the end user to refine the search results using various attributes of your content. They are viewable “post-search”, since they’re dependent on the search query. There are three types of facets: standard facets, numerical facets, and hierarchical facets. For standard and hierarchical facets, the only setup you have to do in the Search configuration is setting the field as a facet in searchable fields.

In addition to this configuration, numerical facets require additional setup using the facets object to define the numerical ranges to use. The available fields are listed below. There are three options for setting ranges.

Check out the Set up Standard Facets guide for details on the setup you would use for each of the three setup options.

Facet Order

You can set the order in which facets appear on the frontend for each vertical. The facets at the top of the list will get the most attention. Consider placing the most general, high-level filter categories at the top of the list and the more specific ones at the bottom. If you don’t specify an order, the algorithm will determine this for you. Check out the Facets and Filters (Backend) unit for more detail.

Use the facetOrder array to specify the order you want facets to appear in. Any facets that appear on a given vertical that are not included in the facetOrder property will be shown in an arbitrary but consistent order, chosen by the algorithm.

For example, the below designates the facet order as restaurant type, then restaurant features for the Restaurants vertical.

    "restaurants": {
      "facetOrder": [
        "c_restaurantType",
        "c_restaurantFeatures"
      ]
    }

Minimum Location Radius

Minimum location radius can be used to set a minimum on the radius of geolocation filters applied. By default, if a user searches for a place, Search will automatically pick a radius based on the size of that place. You may want to set a higher minimum radius if your business has wide service areas, for example. Learn more in the How Geolocation Filters Work reference doc.

As with all distance filters, minLocationRadius is set in meters. The following sets a minimum radius for the Locations vertical to 400 miles or 643738 meters.

    "locations": {
      "minLocationRadius": 643738.0,
    }

Name

This is the display name of the vertical, which is shown in vertical header and vertical navigation below the search bar, unless overridden on the frontend.

Inferred Filter Order

Inferred filters create a black and white filter with the best exact match (see the Searchable Fields section for more detail). In some cases, however, the same filter value exists in two different fields that have Inferred filter turned on. In a scenario like this, the actual filter that is selected and applied is arbitrary. With the nlpFilterOrder array, you can specify the order in which you’d like Inferred filters to be selected when conflicts happen.

Validation code dictates that any field name put in the nlpFilterOrder array must be a searchable field with Inferred filter enabled.

As an example, a healthcare client has Cardiology as a value in their specialties field and their builtinFile.medicalConditions field. Before nlpFilterOrder, a search for “cardiology near me” would trigger one of these filters arbitrarily. Below is what a config might look like to specify specialties showing up first in the Facilities vertical, which means it will be given priority in the case of a tie.

    "facilities": {
      "entityTypes": [
        "healthcareFacility"
      ],
      "name": "Facilities",
      "nlpFilterOrder": [
        "specialties",
        "builtinFile.medicalConditions"
      ],
      "searchableFields": {
        "builtinFile.medicalConditions": {
          "nlpFilter": true
        },
        "specialties": {
          "nlpFilter": true
      },
      "source": "YEXT"
    }

Saved Search ID

Use a Content saved filter to specify the entities that are allowed to be returned in a given vertical. Each vertical may only have one saved filter. You’ll want to include this if you need to limit the entities returned for a vertical in some way, for example only those locations that are open, FAQs that have the Answer field filled out, or events that are in the future. To obtain the ID for a saved filter, follow the View Saved Filters help article.

If no saved filter is specified, all entities of the entity types enabled for the vertical could be returned.

Check out the Overview of Verticals unit for more details.

Below is an example of an Events vertical using savedSearchId:

    "events": {
      "entityTypes": [
        "event"
      ],
      "name": "Events",
      "savedSearchId": "125019244"
    }

Searchable Fields

Advanced Search Tier Features

Semantic search, Inferred filter (except builtin.location), and document search are only available on the Advanced Search tier. Check out the Search Tiers reference doc to learn more about the features that are available in each tier.

Searchable fields tell the algorithm which fields on each vertical to index and how. These searchable fields then affect which results are returned to the user.

Within the searchableFields object, list each field you want to make searchable as an object, and then within that object, list each searchable field type you want to enable as true. The only searchable field type not available in the UI is static filter. For more information on common use cases, check out the Searchable Fields Best Practices reference doc.

The possible searchable field types are listed below:

Special Inferred Filter Uses

There are special Inferred filters that leverage a “built-in” entity value. We will go through the three most common built-in Inferred filters below (all are available through both the UI and JSON):

builtin.location

Using this searchable field will enable address search features, like searching a zip code (10011), address line 1 (61 Ninth Ave), city (New York), state (NY), and “near me”. The address searching is possible because of our built-in address field for entities and its associated information, like latitude/longitude.

Note, it is NOT searching through the address field values. A search for “New York” may return locations outside of that state if they are nearby. To search by a field, set an Inferred filter for that specific field, e.g. address.region.

builtin.entityType

As a standard practice, use the builtin.entityType Inferred filter for each of your vertical search configurations. This returns the relevant vertical for searches for an entity type. Additionally, for verticals with more than one entity type, enabling this filter will return the respective entity types within that vertical search.

builtin.hours

Using this searchable field will enable searching an entity’s hours of operations. Today, this Inferred filter only supports “open now” intents, so a user could search “restaurants open now” and get a list of restaurants that are open with consideration of a user’s time zone and the entity’s holiday hours.

Here is an example of a Restaurants vertical that includes the following configuration:

• Special Inferred filter uses for both builtin.entityType and builtin.location
• An entity relationship using the name field from the related Event entities through the c_promotingEvents field

• A field (c_restaurantFeatures) with multiple searchable field types enabled

  "restaurants": {
    "searchableFields": {
      "builtin.entityType": {
        "nlpFilter": true
      },
      "builtin.location": {
        "nlpFilter": true
      },
      "c_promotingEvents.name": {
        "nlpFilter": true
      },
      "c_restaurantFeatures": {
        "facet": true,
        "nlpFilter": true
      },
      "c_restaurantType": {
        "facet": true
      },
      "name": {
        "textSearch": true
      }
    }
  }

Semantic Thresholds

Semantic thresholds are the minimum semantic score individual entity results must meet to be returned. You can set separate minimums for universal search and for vertical search.

In the example below, the help articles vertical has a threshold of 0.4 for vertical search and 0.5 for universal search.

    "help_articles": {
      "semanticThresholds": {
        "results": {
          "minimumVerticalSearch": 0.4,
          "minimumUniversalSearch": 0.5,
        }
      }
    }

Semantic Vertical Bias

Semantic vertical biases are adjustments you can make to the final score of each vertical, which determine the rank in which they appear. Biases are limited from -1 to 1 (inclusive) and can only include a single decimal point.

Check out the Vertical Ranking unit for more details.

In the example below, the Help Articles vertical has a semanticVerticalBias of 0.2, boosting the vertical by 0.2 for all searches:

    "help_articles": {
      "semanticVerticalBias": 0.2
    }

Semantic Vertical Intents

Semantic vertical intents are phrases that you want to associate with that vertical as a whole, like a synonym for the vertical. A good way to think about vertical intents is to ask yourself: if this intent was placed as a search query, would I want this vertical to always return first?

Check out the Vertical Ranking unit for more details.

In the example below, the Help Articles vertical uses semanticVerticalIntents to assign some synonyms to the vertical:

    "help_articles": {
      "semanticVerticalIntents": [
        "support",
        "how to"
      ]
    }

Semantic Vertical Threshold

Semantic vertical thresholds are minimum score requirements that a vertical must meet in order to be returned at all in the universal search results. A vertical will always be returned in vertical search. Thresholds are limited from 0 to 1 (inclusive) and can only include a single decimal point.

Check out the Vertical Ranking unit for more details.

In the example below, the Help Articles vertical has a semanticVerticalThreshold value of 0.4, meaning the vertical must have a score of 0.4 to appear in universal search.

    "help_articles": {
      "semanticVerticalThreshold": 0.4
    }

Semantic Vertical Ranking Priority Fields

Semantic vertical ranking priority fields are a select list of the searchable fields that you want the algorithm to prioritize for a vertical when evaluating vertical ranking. If two verticals are tied and have the same vertical score, the Search algorithm will use priority fields as a tiebreaker: looking at the top entities returned on each vertical, matches on priority fields are ranked above other matches.

Check out the Vertical Ranking unit for more details.

In the example below, the Help Articles vertical ranks fields in the semanticVerticalRankingPriorityFields property:

    "help_articles": {
      "semanticVerticalRankingPriorityFields": [
        "name",
        "c_category"
      ]
    }

Sort Bys

The default sort order is the order in which entity results are returned for a specific vertical. If you don’t set a default sort order for a vertical, the Search algorithm will determine it for you, based on relevance, which includes location bias to the user (when applicable).

You also have the ability to customize the default sorting for each vertical, should you want to adjust the order beyond relevance.

In the sortBys array, specify each sorting rule as a separate object with the following properties:

Sorting Types

The available options for sort type are:

In the example below, the Events vertical uses all four types of sort, with the sorting rules as follows:

• Relevance, with relevance algorithm set to match query tokens of the results. Any results with an equal amount of tokens matched will use the next sorting criteria (in this case, distance) to determine their sort order.
• Distance, with buckets for 8046.72 meters (5 miles), 80467.2 meters (50 miles), and 160934.0 meters (100 miles)
• Field, using the Start Time field sorted in ascending order

• Random

  "events": {
    "sortBys": [
      {
        "relevanceAlgorithm": "MATCH_QUERY_TOKENS",
        "type": "RELEVANCE"
      },
      {
        "buckets": [
          8046.72, // 5 miles
          80467.2, // 50 miles
          160934.0 // 100 miles
        ],
        "type": "ENTITY_DISTANCE"
      },
      {
        "direction": "ASC",
        "field": "time.start",
        "type": "FIELD"
      },
      {
        "type": "RANDOM"
      }
    ]
  }
    

Source

The source is the data source used for the vertical. Any vertical created in the platform UI will set the source as YEXT, which means the vertical pulls data from the Content.

In the JSON editor, you can also add third-party backends (see the Search Config - Third Party Verticals reference doc for more details).

In the example below, the Help Articles vertical uses content from the platform, so the source is YEXT.

    "help_articles": {
      "source": "YEXT"
    }

Vertical Key

The vertical ID uniquely identifies the vertical within the experience. This is set when you create the vertical. While it is possible to change the vertical key here, it is discouraged due to potential downstream consequences. If you do change it, make sure to update any references to the same vertical key, particularly in the frontend.

Vertical Type

The vertical type specifies the search tier used by the vertical. This only applies when the source is Yext. Currently options are “BASIC” or “ADVANCED”.

If vertical type is not specified and your account only has one of the two subscriptions, all verticals will default to that search tier. However, if your account has both the Basic Search subscription and the Advanced Search subscription, any vertical without a search tier specified will default to the Advanced Search tier.

Check out the Search Tiers reference doc to learn more about search tiers and the features that are available in each tier.