Categories | Yext Hitchhikers Platform
This article explains the Categories system in Yext Content and how categories can be managed.
You will need the following permissions to manage categories:
- Edit access on the Categories field
- Optional: Access to modify categories (by default, Yext customers cannot edit categories once they are set. To get access to modify categories, please reach out to your Client Success Manager.)
Overview
A category is a designation that describes an entity. For example, if a location entity were created for Yext, the category would be software company.
Categories are primarily used in Listings, where they help publishers like Google properly index businesses and industry professionals. They are structured hierarchically and typically consist of a parent category and subcategories. For example, an entity for a healthcare professional who specializes in dermatology might have a category of Health & Medicine > Medical Specialties > Dermatology.
Categories are also scoped to an entity type, meaning that entities can only be assigned categories that are relevant to their entity type. For example, the “Restaurant” category cannot be assigned to an Event entity.
Each entity can be assigned one primary category and up to nine additional categories, for a total of 10 base categories. (10 categories is the maximum number of categories per entity that Google and other publishers typically accept.)
Where to Use Categories
Categories can be viewed and managed in the following places in Yext:
- Content > Configuration > Category Lists: Download a full list of assignable categories based on your account’s base list.
- Entity Edit: See the category applied to a single entity or set of entities
- Connectors
Categories can also be accessed via API: * Management APIs > Categories & Google Attributes * Management APIs > Suggestions
Category Lists
A category list is a consolidated list of available categories. Each publisher has its own category list, with its own taxonomy of category names and internal IDs (for example, Google’s “Accounting firm” category has an ID of gcid:accounting_firm).
Yext maintains a category list, and also stores various publisher category lists in order to properly map categories on an entity between different publishers. While these lists are not exposed in the platform, many publishers make their own category lists publicly available.
Below are some commonly used publisher category lists:
Category Mappings
Category mappings translate categories on entities between publisher category lists, so that the category remains consistent from one publisher to another. Yext manages these category mappings between the Yext category list and individual publishers’ category lists.
Once a category is assigned to an entity, Yext determines which categories in the publishers’ lists to map the assigned category to.
Base Category List and Category Overrides
As mentioned above, Yext maintains its own category list and maps these to different publisher lists. If a mapping is determined to be incorrect, there is also an option to override a category mapping.
The base category list (or “base list”) exists in every Yext account and lists the categories are available for assignment on entities. Base-list categories are what appear when you search in the Categories field on an entity.
Category Overrides
If a user or publisher disagrees with a category mapping in Yext, or if a base list category cannot be mapped to a certain publisher, the category can be changed with a category override. Category overrides allow a user or system (i.e., a connector or app) to specify a category directly from a publisher category list, overruling the mapping configured by Yext.
For example: a location’s primary category in Yext is set to “Business Services > Computer Services”, which Yext maps to the “Computer Support and Services” category on Google. If you wanted to change this to instead use the “Computer Repair Service” category in Google, you could override the Google Business Profile category.
View Mappings and Overrides
Mappings and category overrides can be viewed and managed in the following ways in Yext:
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 steps, see the training unit on Advanced Category Management .
Connectors
When ingesting data via a 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 the Yext category with the
Map Publisher Categories
transform. This converts the publisher category ID to the mapped Yext category ID. For example, this transform will convert the gcid:apartment_building category from Google Business Profile to the corresponding Yext category ID 1686.
You can also override category mappings in Connectors. In the Mapping stage of your connector configuration, map the publisher category ID to the appropriate subfield for the desired publisher endpoint.
Currently, Connectors only support mapping to the following category lists:
- Base category list (Yext)
- Bing
- Facebook Place Topics
- Google Business Profile
- TripAdvisor Listing
General notes on categories in Connectors:
- Categories are assigned in the order received by the connector. The first category received by the connector will be the primary category, and all subsequent categories will be treated as additional categories.
- Connectors offers a Google Business Profile native source. If you are ingesting data from GBP, take a look at the Google Business Profile reference .
Suggestions API
Category overrides can be viewed in the Suggestions API. Publishers commonly send override categories through the Suggestions system, via Publisher Suggestions. The Suggestions API returns 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.
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). 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)
- Array of values corresponding to the publisher category IDs. These are determined by the publisher (e.g.,
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 1 + the number of overrides set.
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 .