Google Business Profile | Yext Hitchhikers Platform

Overview

Use the Google Business Profile source to pull your Google Business Profile entities data into Yext Content.

Operations

• Fetch Locations: pull in all locations from the linked Google account.
• Fetch Locations with Filters: import a subset of the locations in one of your Google Business Profile location groups.
• Fetch Hotels: this operation is specifically for Hotel entities, as Google has a separate Lodging endpoint that pulls in location information specifically for hotels and hotel-specific information.

Settings

Location Group

This is the ID associated with the Location Group in Google Business Profile.

Filter

For the Fetch Locations with Filters operation, there is an input to add labeled Filters.

Here, input the field you would like to filter on, to specify what data you want to pull into the platform.

See Google’s API documentation on filtering to learn what syntax is expected.

The base URL of the API call sent to Google with this operation looks something like this:

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask=name,languageCode,storeCode,title,phoneNumbers,categories,storefrontAddress,websiteUri,regularHours,specialHours,serviceArea,labels,adWordsLocationExtensions,latlng,openInfo,metadata,profile,relationshipData,moreHours&filter=

Whatever you input in the Filter field will be appended to this URL, and you can filter based on any field. For example, in order to pull in only restaurants in a location group that are categorized as “Bed and Breakfast” or “Cottage”, input categories=bed_and_breakfast+OR+categories=cottage in the Filter field. Or, to only input locations in Great Britain, you could add the filter input storefront_address.region_code="GB".

When filtering by a category, make sure not to include the gcid portion of the ID. See the Category List below for all available categories.

Recommended Transforms

Because Google exports data in a slightly different format from the way Yext has to ingest it, you’ll likely need a few transforms in any connectors that you build from scratch.

Below are some recommended transforms for building a connector using the GBP source:

Address

1. Google returns addresses in one field called addressLines, but Yext accepts addresses in separate lines. Use a Split Column transform with a comma delimiter to create three new columns for each line of the address.
2. Map each of these selectors to the fields Address > Line 1, Address > Line 2, and Address > Line 3.

Categories

1. First, you will need to map both the Primary Category and Additional Categories to the Yext Category field. Use a Merge Columns transform to combine these two fields.
2. Call the new field Categories and map to the Yext Categories field in the final stage of the connector.
3. Use a Find and Replace transform to strip both category fields of their categories/ prefix, which Yext cannot ingest.
4. Use the built-in Map Publisher Categories field to translate Google Category IDs into Yext Category IDs.

Hours

1. Make sure to create selectors for opening and closing times for each day of the week, as you’ll need to map them all separately.
   • The selector JMESpaths should look something like regularHours.periods[?openDay=='MONDAY'].openTime.
2. Then, choose one of the following:
   • Write a typescript function to convert the formatting into HH:DD, or
   • Use a series of Find and Replace or Extract Text transforms.

If you get stuck, download an out-of-the-box connector and apply one of the function transforms included, such as handleHolidayHours or convertAdditionalHours.

Troubleshooting

Below are common reasons for entity failures in connectors using the GBP source, and steps to address them. Note that at this time, if an entity’s field contains an invalid value, the entity will fail and no fields will be brought into Content.

Address Errors

To ensure accurate location listings, pages, and search results, Yext maintains strict address validation that might cause GBP entities to fail. The two most common reasons for failure when using the connector apps are:

• “Value is not a valid region.” (the Region field is blank, or the state code is invalid)
• “Address must include a city.” (the City field is blank)

Google Business Profile allows you to upload locations that do not contain addresses or cities; however, Yext does not. There is no reason not to update this data in GBP, so the best solution is to ensure that the corresponding locations contain accurate values in Google.

Duplicate Entity ID

Occasionally, users will have multiple locations in their Google Business Profile instance that contain the same store code. That will cause the following error to surface in the Entity Diagnostics sheet:

• Error creating entity: DUPLICATE_EXTERNAL_ID

Because the connectors automatically map GBP Store Code to Entity ID in Yext, and the platform does not allow duplicate entity IDs, you will want to ensure that the Store Codes in Google are unique. The Entity Diagnostics sheet will tell you exactly which entities contained duplicate external IDs.

Photo Validation Errors

To maintain parity between Yext Content and Google listings, photo size requirements are consistent between Yext and Google’s APIs. However, Google’s validation for manual photo uploads (rather than API uploads) is slightly looser. For example, photos have a minimum size requirement of 250 x 250px when uploading to GBP via API, but you can manually upload a photo of size 230 x 230px.

Any photos manually uploaded to Google that do not meet their upload requirements will fail in the Yext connector framework. On the Entity Diagnostics spreadsheet, you may see one of the following errors:

• “Width must be at least 250 pixels” (photo is too small)
• “Height must be at least 250 pixels” (photo is too small)
• “Error uploading photo: Image Content-Length is greater than 5242880” (photo is too large)

Find the field that triggered the error. It will be one of the following:

• Photo Gallery
• Google Cover Photo
• Google Logo

To handle these errors, you can take one of the following actions:

1. Remove the photo from the location in Google Business Profile.
   • In the Entity Diagnostics file, look at which entity failed. The ID in this column will reflect the Store Code ID in GBP. Find that location in your GBP instance and remove the photo causing the error.
2. Unmap the corresponding photo field in the connector framework.
   • Identify the correct field, then return to the last step of the connector configuration.
   • Unmap the corresponding field by clicking on the field, selecting Clear, and then Apply.

Category List