Categories | Yext Hitchhikers Platform
This reference article explains the Yext Categories system and the various interfaces through which categories can be managed.
Permissions
Because Categories majorly impact Listings, specific permissions are required to fully manage them. Much of this article presupposes the following:
- User has Edit access on the Categories field
- User can subsequently modify categories. By default, direct Yext customers cannot edit categories once they are set. To obtain access to modify categories, please reach out to your Client Success Manager.
Overview
A Category is simply a single designation that describes an entity. For example, Yext is a software company. Categories are primarily used in Listings, where they describe entity types such as Locations and Restaurants, and help publishers like Google properly index businesses.
Categories are structured hierarchically and typically consist of a parent category and its subcategories. For example, a healthcare professional who specializes in dermatology might have a set category of “Health & Medicine > Medical Specialties > Dermatology”.
Categories are also scoped to an Entity Type. As such, entities can only be assigned categories that are eligible for their entity type. For example, the “Restaurant” category cannot be assigned to an Event entity.
Categories can be viewed in the following interfaces:
- Content > Configuration > Category Lists: Users can download a full list of assignable categories based on their account’s base list, which we will discuss in a later section. Note: users must select an Entity Type, Country, and Language before exporting this list.
- Entity Edit
- Connectors
- Management APIs > Categories & Google Attributes
- Management APIs > Suggestions
Assigning Categories
Users can assign one primary category and nine additional categories, for a total of 10 base categories, to a single entity. This accords with the maximum number of categories per entity that many publishers like Google accept.
The Primary Category is the first category in your list of assigned categories, and it should reflect how your location or entity primarily identifies. It is recommended that Google Business Profile (GBP) users choose their Primary Category carefully, as sending Google a questionable category can greatly impact Listings.
Note that Brand categories are largely a legacy feature and can be ignored by most users.
Category Lists
A Category List is a single categorization system or consolidated list of categories. Each category belongs to a single Category List, each owned by a single publisher and possessing its own particular taxonomy of category names and IDs (for example, GBP’s “Accounting firm” category has an ID of gcid:accounting_firm).
Yext maintains its own category list, as do some resellers and publishers like Google and Apple. Yext stores Publisher Category Lists in its system for list-to-list mapping, and while Yext does not typically expose these, many of the lists referenced in the system are made publicly available by Publishers.
Below are some commonly used Publisher Category Lists:
Category Mappings
Mappings translate categories from one category list to another. Yext maintains a complex taxonomy of mappings between its own list and publishers’ category lists.
Once a category is assigned, the Yext system determines which categories in publishers’ lists to map the assigned category to. You can view these mapping determinations by clicking into the Categories field in Entity Edit and clicking Advanced.
Base List Categories vs. Overrides
As mentioned above, in addition to Yext’s own list, the categories system stores lists per publisher and maps these lists to one another. There are two generic types of list categories that appear in your account.
Base List Categories
Each account uses a Base Category List which determines which categories are available for assignment. Base List categories appear when searching on the Categories field in Entity Edit.
The Base Categories List is set at the account level and is determined by the partner owner. Direct Yext customers (i.e., most Yext accounts) use Yext’s own Base Categories List, which comes pre-configured with Yext’s mappings to myriad publishers’ category lists.
Category Overrides
Sometimes users or Publishers disagree with Yext’s mapping determinations. Or, in other cases, Yext is unable to map a base list category to a publisher’s category list. Category Overrides allow a user or system (e.g., a connector or app) to specify entity categories directly from a publisher’s list, thereby overruling the mappings configured by Yext.
For example, suppose a location’s primary Yext category is set to “Business Services > Computer Services”, which Yext maps to the “Computer Support and Services” Google Business Profile category. A user may wish to set their Google Business Profile Category to “Computer Repair Service” instead. In this case, they may override the Google Business Profile Category.
View Mappings and Set Overrides
You can view category mappings and set their overrides in the following interfaces.
Entity Edit
Categories and their mappings can be viewed by clicking Advanced while editing the Categories field in Entity Edit. This will open the Advanced Category Manager.
Categories can be overridden from the Advanced Category Manager by selecting the desired publisher endpoint and clicking the Override Category checkbox. For a brief how-to guide, follow the Hitchhikers unit on Advanced Category Management .
Connectors
If you are ingesting data via Connector, you can map column values to the Categories field in the mapping stage.
If you are pulling in Listings data from a supported publisher, you can set your Yext category by utilizing the
Map Publisher Categories
transform, which converts the publisher category ID into the mapped Yext category ID (this is a numeric value). For example, this transform will convert the gcid:apartment_building category from GBP to Yext category ID 1686. This transform can also return multiple Yext category IDs given a comma-separated list of IDs.
Category Overrides in Connectors
You can also override category mappings in Connectors. In the Map Data stage of your Connector configuration, simply map the publisher category ID to the appropriate subfield (i.e., publisher list) for the desired publisher endpoint.
Currently, Connectors only support mapping to the following category lists:
- Base Category List (e.g., Yext)
- Bing
- Facebook Place Topics
- Google Business Profile
- TripAdvisor Listing
To request mapping support for additional publishers, please reach out to your Client Success Manager or submit to Ideas .
General notes on categories in connectors:
- Categories are assigned in the order received by the connector. The first category received via connector will be the primary category, and all subsequent categories will be treated as additional categories.
- The provided category list will overwrite the entire list on that entity. This is because today, connectors do not support appending items to a list field, and the entire provided List is assumed to be a comprehensive set of data.
- Category mappings are at the subfield level (i.e. you can map to the Base List, or a specific publisher’s list, like to GBP or Yelp overrides).
- As part of connector error handling, if a non-existent category ID is referenced during a connector run, the field-level update will be ignored, but all other updates to the entity will be processed.
- Connectors offers a Google Business Profile native source. If you are ingesting data from GBP, we recommend taking a look at the Google Business Profile reference .
Suggestions API
Category overrides can now be viewed in our Suggestions API endpoints. This is particularly useful since publishers commonly send override categories through the suggestions system, via Publisher Suggestions. Previously, only suggestions made on the Base Category List were returned. Thus, for most accounts, publisher suggestions were unavailable via API. Today, the Suggestions API returns Suggestions (including publisher suggestions) on category overrides in addition to the Base List Categories.
Note that in order to view category overrides in the Suggestions API, the v parameter must be greater than or equal to 20230401.
Viewing suggestions: Use the Get or List endpoint to view suggestions. Here is an example response:
"response": {
"suggestions": [
{
"uid": "12345678",
"accountId": "1234567",
"createdDate": "2023-02-02T13:53:54Z",
"lastUpdatedDate": "2023-02-02T13:53:54Z",
"source": {
"appId": "12345"
},
"entityFieldSuggestion": {
"entity": {
"id": "my-entity",
"uid": "12345678",
"type": "location",
"folderId": "",
"labels": []
},
"existingContent": {
"categories": {
"yext": [
"1"
],
"apple": [
"localservices.itservices"
],
"googleBusinessProfile": [
"gcid:software_training_institute"
]
}
},
"suggestedContent": {
"categories": {
"yext": [
"2"
],
"apple": [
"localservices.itservices",
"professional.softwaredevelopment"
],
"bing": [
"123456",
"234567"
],
"googleBusinessProfile": [
"gcid:software_company"
]
}
}
},
"status": "PENDING",
"locked": false,
"comments": []
}
}
}Note the structure of the categories object:
{
"categories": {
"yext":["2"],
"googleBusinessProfile":["gcid:software_company"]
}
}The categories object includes:
- Base List ID (usually Yext, but not always). The Base List is always returned.
- Yext Category ID (numeric)
- Publisher List ID (e.g.,
googleBusinessProfile)- Array of values corresponding to the publisher category IDs. These are determined by the publisher (e.g., “gcid:software_company”) The “categories” object only includes a property for the particular category list if it is specifically set. Therefore, the number of properties in the object is equal to the 1 + the number of overrides set.
The categories object only includes a property for the particular category list if it is specifically set. Therefore, the number of properties in the object is equal to the 1 + the number of overrides set.
Creating suggestions: Use the Upsert endpoint to create a suggestion. Here is an example request:
"entityFieldSuggestion": {
"entity": {
"uid": "{entity_uid}"
},
"suggestedContent": {
"categories": {
"googleBusinessProfile": [
"gcid:software_company"
],
"yext":["291","1234"]
}
}
}Category suggestions made via the Suggestions API are partial. In other words, categories provided per property (e.g., googleBusinessProfile) are considered comprehensive, but any properties left out of the request payload will remain untouched.
For additional information on making Suggestions API requests, see the Suggestions API documentation .
Limitations
Categories do not appear in Entity History, as they are currently stored externally to Yext Content. As such, the Categories field and its values are not part of an entity profile in the same way the “Description” or “Name” fields and their values are. We plan to support this in a future release.
The Entities API does not currently return Category Overrides. Only categories from the base list will be returned. We plan to update this in a future release.