Summer ’18 API Updates

Summer18BlogPost

As the structured data consumers seek about your business continues to grow, being able to effectively store, manage, and publish the public facts about your brand becomes more crucial. To help you do so, we’ve made the following updates to our APIs in the Summer ’18 Release.

Preparing for Entities endpoints

At Yext, we recognize that the public facts about your business extend beyond your location details — they also include data about the events and people that set your business apart from the competition. To more accurately reflect these different aspects of your business, we will soon be introducing Entities endpoints in the Knowledge API, which are meant to be used in place of the Locations endpoints. Once the Entities endpoints become available, Locations endpoints will still be supported, but no new functionality will be added to them.

In this release, we have begun making changes to our APIs to support the storage and analysis of entity data:

Custom Fields data model:
  • Added the ability to specify custom id values (only supported in Entities endpoints)
  • Added the entityAvailability field to indicate the types of entities the custom field is available to
  • In the type field, renamed the “LOCATION_LIST” value to “ENTITY_LIST”
Create Report endpoint:
  • Added entityIds, entityType, and entityGroup filters
  • Added “ENTITY_IDS”, “ENTITY_TYPES”, and “ENTITY_GROUPS” values to dimensions

The Entities endpoints are not yet available, and there is no action required on your part at this time. We will keep you updated on the release of the Entities endpoints, and we will give you the time and information you need to incorporate these endpoints into your integration.

“PowerListings®” endpoints are now “Listings” endpoints

Just as the types of business data you can store in Yext continues to grow, so does the variety of data partners we sync it with. In addition to directory sites, consumers can discover information about your business from maps, apps, voice-enabled devices, and virtual assistants. To reflect the evolution of our network of data partners, we’ve renamed the “PowerListings® Network” to the “Yext Knowledge Network” and, in turn, have changed the name of the “PowerListings®” endpoint group in the Knowledge API to the “Listings” endpoint group. This change appears in both the documentation and the endpoint URLs.

For updated information about our Listings endpoints, see the Knowledge API documentation.

New Features

In addition to preparing for the Entities endpoints and expanding our network of data partners, we added two new endpoints as part of the Summer ’18 Release.

Comment: Update and Comment: Delete endpoints in the Knowledge API

Prior to this release, the review-response capabilities of the Knowledge API were limited to creating comments on reviews and responding to previous comments. The addition of the Comment: Update and Comment: Delete endpoints makes it possible to edit and remove comments on your reviews via the Knowledge API.

To learn more about these endpoints, see the Knowledge API documentation.

Improvements

The Summer ’18 Release includes the following enhancements to our APIs.

Improved filtering of Duplicates: List responses

When sending requests to the Duplicates: List endpoint, you can now choose to retrieve information about duplicate listings with any status or to only retrieve duplicate data for listings whose status is “LIVE”. By filtering the response to only include data about live listings, you can easily focus on those duplicates that may be confused for your Yext-powered listings that are currently visible to consumers.

For more information on Duplicates: List requests and responses, refer to the Knowledge API documentation.

Ability to specify how Assets can be used

If you would like to restrict certain Assets to be used only in review responses, social posts, or Knowledge Manager fields, you can do so by selecting the appropriate type value in the Asset data model’s new usage field. You can also specify the Knowledge Manager fields that the Asset can be applied to by listing those fields in the fieldNames subfield.

More details about the Asset usage field can be found in the Knowledge API documentation.

Translations of Custom Field options

With the new translations subfield of the Custom Fields data model, you can now store translations of the options you’ve specified for single-option and multi-option Custom Fields. Please note that if you choose to use this feature, you will need to provide these translations, as Yext will not translate your option text for you.

To learn more about the translations subfield, see the Knowledge API documentation.

Reviews enhancements

This release includes the following additions to the Reviews data model and endpoints:

  • reviewLanguage field and parameter — If we are able to detect the language of the review, we will indicate the language in this field. With the reviewLanguage parameter, you can filter Reviews: List responses to include only reviews that are written in the languages you specify.
  • reviewLabels field and labelIds parameter — The reviewLabels field lists the labels you’ve added to reviews via our web interface. The addition of the labelIds parameter to the Reviews: List endpoint lets you retrieve data about reviews with specific labels.
  • reviewExternalId parameter — The reviewExternalId parameter for Review: Get and Reviews: List requests allows you to find data for the review with the publisher-assigned ID you specify.

More information about these enhancements can be found in the Knowledge API documentation.

Analytics enhancements

We’ve added the following metrics, dimensions, and filters values to the Create Reports endpoint:

metrics:
  • “IST_AD_MATCHES”
  • “IST_AD_PRESENCE”
  • “KEYWORD_SENTIMENT”
  • “KEYWORD_MENTIONS”
  • “ST_EVENT_SHARE_OF_INTELLIGENT_SEARCH”
  • “ST_EVENT_RICH_RESULT_PRESENCE”
  • “ST_EVENT_MATCHES_PER_SEARCH”
  • “EVENT_SEARCHES”
  • “EVENT_PROFILEVIEWS”
  • “TICKET_CLICKS”
  • “EVENT_SEARCHES”
dimensions:
  • “REVIEW_KEYWORDS”
  • “EVENTS”
  • “EVENT_SEARCH_CONDITIONS”
  • “PUBLISHERS”
filters:
  • eventSearchCondition

To learn more about these additions, see our Knowledge API documentation.

New API Fields

In addition to the fields mentioned previously, the following fields have been added to our APIs:

Locations:
  • sourceUrl in photos — the URL the image was uploaded from, if applicable

Questions?

If you would like more information about any of these features, or if you need assistance using them, please contact our API support team.