Fall ’17 API Updates

Fall17Updates_1560x878

We’ve focused our Fall ’17 Release on structuring your business knowledge so automated services and search technologies can more easily understand it. And, because consumers often decide whether or not visit a store based on its reviews, we’ve also included a number of enhancements to help you manage this special form of business knowledge.

New Features

We have a number of great enhancements to our API in the Fall ’17 Release.

Schema support

Yext’s Schema support gives you the ability to add Yext-powered structured data, which consists of the public facts about your business you already store in the Knowledge Manager, and simple analytics onto any page of your website with a few lines of code. Having structured data on your site allows search engines to readily recognize the kinds of data you are publishing and surface it to consumers.

If your subscription includes both Knowledge Tags and the Live API, you can use the Schema endpoint to retrieve a location’s Schema information. Similarly, the new schemaTypes field in the Location data model shows which Schema types have been applied to a location.

More details about the Schema endpoint and schemaTypes field can be found in the Live API documentation and Knowledge API documentation, respectively.

Review Labels support

Our new Review Labels feature allows you to tag reviews, making it easier to find, organize, and sort the reviews you monitor through Yext. The labelIds field in the Review data model lists the labels that have been applied to a review.

To learn more about labelIds, see the Knowledge API documentation.

Review Invitations endpoints

Prior to this release, clients using our Review Generation feature had no way to view or search for review invitations via the Knowledge API. We’ve added Review Invitation: Get and Review Invitations: List endpoints, which allow you to retrieve specific invitations or search for invitations that have certain properties.

For more information about these new endpoints, see the Knowledge API documentation.

Add Request webhook

Partners with access to our Administrative API are now able to use the Add Request webhook to monitor additions to their locations’ services. For example, rather than polling the Administrative API to check the status of your request to add a new location and its subscription, you can now configure the Add Request webhook to notify you when the status of your request changes.

To learn more about the Add Request webhook, see the Webhooks documentation.

Improvements

In addition to adding new features, we’ve made the following improvements to our APIs and the API user experience.

Simplified pagination of Reviews: List response

If you’re using Yext to monitor your reviews, requests to the Reviews: List endpoint may span several pages. As an alternative to specifying the limit and offset parameters in your requests, you can now use the limit and pageToken parameters to paginate your results.

When there is an additional page of data to show, the nextPageToken field will be included in your response. You can pass this field’s value as the pageToken parameter in a future request to retrieve the next page of data.

To learn more about pageToken and nextPageToken, see the Knowledge API documentation.

Retrieve first-party reviews with a particular status

The Reviews: List endpoint now has a status parameter, which allows you to search for first-party reviews that have the status you specify.

  • “LIVE”
  • “QUARANTINED”
  • “REMOVED”

Please note that the “QUARANTINED” and “REMOVED” statuses only apply to reviews you have collected with our Review Generation feature.

For more information about status and other Reviews: List request parameters, see the Knowledge API documentation.

Internationalization of Reviews date parameters

Prior to this release, the following parameter values for the Reviews: List endpoint were based on Eastern Standard Time:

  • minPublisherDate
  • maxPublisherDate
  • minLastYextUpdateDate
  • minLastYextUpdateDate

To align our time calculations with international standards, we are now using Coordinated Universal Time (UTC) to determine which reviews are returned when these parameters are passed.

More details about these and other Reviews: List parameters can be found in the Knowledge API documentation.

Analytics enhancements

With this release, we are adding the following metrics and dimensions values to our Create Report endpoint:

metrics:

  • “YELP_CUSTOMER_ACTIONS”

dimensions:

  • “WEEK_NUMBER”
  • “DAY_OF_WEEK”

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

Support for Location List custom fields

We’ve added “LOCATION_LIST” as a valid value for a Custom Field’s type, allowing Pages customers to create, edit, and retrieve Location List custom fields via the Knowledge API. With Location List custom fields, you can set up one-way linking between locations (e.g., a hotel and its restaurants, a drug store and its pharmacy, etc.).

Additional information about Custom Field types can be found in the Knowledge API documentation.

Filter Healthcare Professionals by the conditions they treat

The filters parameter in the Live API’s Locations: List and Locations: GeoSearch endpoints now allow you to search for healthcare professionals based on the conditions they treat. For example, you can search for healthcare professionals who treat conditions containing “infection” or conditions starting with “seasonal”. This conditionsTreated filter is also available in Locations: Search requests in the Knowledge API.

To learn more about conditionsTreated and other filter options, see the Live API and Knowledge API documentation.

Unique static IDs for Locations

Previously, App Directory Developers and Partners were only able to identify Locations by their id values, which can be changed. With this release, each Location has been assigned a static, globally-unique uid value, giving our Developers and Partners a reliable means of identifying locations when designing apps and using our APIs.

More information about uid and other Location fields can be found in the Knowledge API documentation.

New API fields

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

Locations:
  • isoRegionCode – the ISO 3166-2 region code for the Location
  • firstPartyReviewPage – link to the review-collection page, where consumers can leave first-party reviews
  • isClusterPrimary – (Healthcare Locations only) indicates whether the Location is the primary Location in its group
Users:
  • lastLoginDate – shows the date the user last logged in to the Yext platform
Duplicates:
  • suppressionType – indicates the suppression method used by the publisher
Menus:
  • url field in items – the URL of the item’s webpage

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.