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.)
Adding categories to your entities is an important step to ensure that the listings for your entities will appear in relevant searches. All the categories you see listed in Yext are predetermined to ensure that entities are listed correctly across publisher sites.
Edit the Category Field on an Entity
- Click Knowledge Graph in the navigation bar and click Entities.
- Click on the entity you would like to edit.
- To edit multiple entities at once, visit the Edit Entities in Bulk article.
- Click on the Categories field.
Follow the steps below to make your desired changes:
Add a category
- Click Add a category.
- Enter the first few letters of the desired category in the text box, and select from the list that appears.
Delete a category
- Click on the trash can icon next to the category you'd like to delete. Reorder categories
- Drag and drop categories on an entity into your preferred order.
- Categories should be arranged in order of importance. The first category is the primary category.
Save changes
- After making your changes, click Save. Read the warning message before proceeding.
- Click I'd like to change my categories to save your changes.
Override the Category on an Entity
Yext uses the Category field on entities to match the entity to the most appropriate category on each publisher. Each publisher has its own set of categories.
In Yext, you can see exactly how an entity is categorized on each publisher and make changes if desired. You can also override these mappings for individual publishers.
- Click Knowledge Graph in the navigation bar and click Entities.
- Click on the entity you would like to edit.
- To edit multiple entities at once, visit the Edit Entities in Bulk article.
- Click to expand the Categories field. Then, click Advanced in the lower right of the field area.
- The Advanced Category Management modal lists the categories that the chosen entity appears for with each individual publisher. The publishers are listed in the left sidebar, and the number next to each publisher indicates how many categories the entity is currently listed under.
- Click on a publisher to view the categories. To add more categories for that publisher, or change the categories, select the Override categories for [Publisher Name] checkbox.
- To add a category to the list, click Add a category.
- To delete a category, click the trash can icon next to the category you would like to remove.
- When finished, click Apply.
Export a Category List
Categories help ensure that your business is listed properly across the Publisher Network. Yext has a predetermined list of categories that are mapped to categories on each site in the Publisher Network. You can export a list of eligible categories for each entity and each available country from Yext.
To export a category list:
- Click Knowledge Graph in the navigation bar and click Configuration.
- Click Category Lists.
- Select the Entity Type and Country you would like a list of eligible categories for.
- Select your Download Language.
- Click on the Download button to export the category list.
You can use this export to update new or existing entities in bulk. See the Upload Entities in Bulk via Entity Upload documentation to learn more.
Category Management Permissions
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.)
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 that 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.
Category Impact on Google Attributes
Categories can also impact Google attributes. Fields for Google attributes will only appear for entities with listings that are synced to Google Business Profile. Available attributes will vary based on category, country and language profile.
For example, a Restaurant entity with the category “Mexican Restaurant” might have attributes like:
- Has Coat Check
- Has Childrens Menu
- Has Bar Onsite
- Has No Contact Delivery
Google will add attributes and make them available to categories over time. If you change your entity’s category, you may see a change in the attributes available.
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)
- Apple
- 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.