Migrating from Locations API to Entities API
With the launch of Yext for Events in Summer ’18, the Yext platform expanded beyond the Location object to other entities that reflect the structured knowledge about your businesses. As the Yext platform continues to expand, it follows that our APIs must evolve with it. In the Fall of 2018, Yext introduced the Entities API Endpoints as a comprehensive solution for managing several different object types. Entities are now the best way to create, update, and manage different objects about your business, including locations. It is important to note that with the introduction of the Entities API Endpoints, no new functionality will be added to the legacy Locations API Endpoints. For this reason, we strongly recommend to anyone utilizing the Locations endpoints to consider migrating to the Entities endpoints and take advantage of new features in the Yext platform. The Entities endpoints are available in the Yext Knowledge API and the Live API.

Basics

There are 6 different entity types (entityType) available. Depending on your Yext subscription, you may not have access to all entity types:
  • Location
  • Event
  • Healthcare Professional
  • Healthcare Facility
  • ATM
  • Restaurant
In the following section, we’ll detail the most important changes to keep in mind when migrating from Locations to Entities.

Entities: What’s Changed?

First and foremost, calls to the Entities endpoint will have a different path than requests currently being made to the Locations endpoint. All calls made to the Entities endpoint will need to be formatted as follows:
https://api.yext.com/v2/accounts/{accountId}/entities
The following Entities endpoints are available, and support POST/PUT/GET/DELETE methods:
  • Entities: Create
  • Entities: Update
  • Entities: Delete
  • Entities: Get
  • Entities: List
  • Entities: Geosearch (Live API only)
  • Entity Language Profiles: Upsert
  • Entity Language Profiles: Delete
  • Entity Language Profiles: Get
  • Entity Language Profiles: List
  • Entity Language Profiles: List All
In addition to the different URL path and new endpoints, there are some additional key differences. Here are some of the most prominent changes to be aware of:
  • Custom Field API Names
    • Custom fields now have API Names, which will now serve as the custom field ID in the API. Unlike the Locations endpoint which requires that the numeric value for the customFieldId is used to specify custom fields in the API, Entities utilize an alphanumeric string known as the API Name. This value can be found under the Custom Fields manager in the Knowledge Manager/Custom Fields section.
    • API Names take the custom field name and append the “c_” prefix to them. They roughly follow the convention of being named with a camel-cased version of the field name (e.g.If Custom Field name = “Serves Hot Food”, then customFieldId = “c_servesHotFood”). The API name can be viewed and / or edited in the platform.
  • Custom Fields Moved Top-level
    • Custom fields are now top-level fields in the Entity object, as opposed to within a customFields sub-field in the Locations API.
  • New Filtering Capabilities
    • Filters work on almost every field, across entity types, and can be combined. Now you can search Entities successfully using the Knowledge and Live APIs.
    • For more information on Filters formatting and conventions, please see the Entities: List endpoint documentation, query parameters section. These filters will also work with the Entities: Geosearch and Entities: List endpoints in the Live API
  • Applying Templates
    • Templates can now be applied via the API by providing a templateId as a query parameter. Similar to custom fields, templates have an API Name, which will be the templateId in API requests. The template API name can be found in the Yext Platform in the UI for managing a particular template.
  • Entity Language Profiles: List All
    • The Locations API enables the API consumer to pull all or specific language profiles for a location, but not for all locations at once. With the Entities Language Profiles: List All endpoint, the API consumer can pull language profiles for all entities in the account in one call.
As part of these changes, the structure of Entities requests/responses has also changed from what you might be familiar with under our Locations endpoints.

New Data Structure

We’ve separated entity metadata into a subfield, which is denoted by our “meta” object with {curly braces}. This meta object contains information stored outside the Entity Profiles. Example:
"meta":{
   "accountId":"00000000000000000",
   "uid":"0oavgm",
   "id":"002",
   "timestamp":"2019-02-04T19:40:01",
   "folderId":"247013",
   "language":"en",
   "countryCode":"US",
   "entityType":"location"
}
All applicable fields stored in meta:
  • accountId
  • uid
  • id
  • language
  • countryCode
  • entityType
  • folderId
  • labels
  • timestamp

What else is new?

  • Another exciting change comes in the form of field names and their structures. Field structures have been brought into parallel with their Entity Upload counterparts. As part of this, it’s important to note that compound fields in the Yext UI will also be compound fields in the API. Example:
    {
     "address":{
          "line1":"1 Drooly Ln",
          "line2":"Apt. 1"
       }
    }
    • This will also apply to “Custom Field Types” as well.
  • Omitting a sub-field of a compound field in a call does not wipe the sub-field. To wipe a field, you’ll need to pass null (no quotes).
  • Custom fields of custom field types be retrieved and updated using their API Name in Entities calls (This functionality is not available under the Locations endpoints, nor will it be added).

See it in action

Let’s take a closer look at some of these updates in practice. URI Format for Entities: List (Method: GET)
GET  https://api.yext.com/v2/accounts/{accountId}/entities?api_key={api_key}&v={YYYYMMDD}
Sample Response:
{
	"meta": {
        "accountId": "4302517710493931126",
        "uid": "vlZJyo",
        "id": "5041913364914905161",
        "timestamp": "2018-12-31T11:46:49",
        "folderId": "0",
        "language": "en",
        "countryCode": "US",
        "entityType": "location"
    },
    "address": {
        "line1": "1 Madison Ave",
        "city": "New York",
        "region": "NY",
        "postalCode": "10001",
        "extraDescription": "Brooklyn"
    },
    "addressHidden": true,
    "name": "Bill's Coffee Joint",
    "featuredMessage": {
        "description": "Rainbow bagels!",
        "url": "http://example.com"
    },
    "isoRegionCode": "NY",
    "mainPhone": "+15185555340",
    "mobilePhone": "+15185556899",
    "timezone": "America/New_York",
    "yextDisplayCoordinate": {
        "latitude": 40.7410895,
        "longitude": -73.98750919999999
    },
    "yextRoutableCoordinate": {
        "latitude": 40.7411640951893,
        "longitude": -73.987830606551
    },
    "categoryIds": [
        "163"
    ],
    "timeZoneUtcOffset": "-04:00"
}
URI Format for Entities: Create (Method: POST)
POST  https://api.yext.com/v2/accounts/{accountId}/entities?api_key={api_key}&entityType=location&v={YYYYMMDD}
Sample Request Body:
{
    "address": {
        "line1": "1 Madison Ave",
        "city": "New York",
        "region": "NY",
        "postalCode": "10001",
        "extraDescription": "Brooklyn"
    },
    "addressHidden": true,
    "name": "Bill's Coffee Joint",
    "featuredMessage": {
        "description": "Rainbow bagels!",
        "url": "http://example.com"
    },
    "mainPhone": "+15185555340",
    "mobilePhone": "+15185556899",
    "meta": {

        "id": "NEWENTITY",
        "folderId": "0",
        "language": "en",
        "countryCode": "US",
        "entityType": "location"
    },
    "categoryIds": [
        "163"
    ]
}
Please Note: It’s required that entityType is included in the request URI when creating a new entity. Entity types cannot be changed once set, with the exception of type: Location, which can be changed to the following types: ATM, Healthcare Facility, Healthcare Professional, Restaurant. This can not be done in the reverse.

Additional Resources

As you migrate from Locations to Entities, we encourage you to take advantage of our Entities API documentation.