The Locations Manager tool in Content Manager allows you to upload a list of locations to use in email and Web-based experiences. You can adjust locations to target people who are within or not within a specified distance of one location or many locations.
You can also use the locations list with two WHO targets: Distance to location and Distance to many locations. The Distance to location option allows you to target site visitors who are within a specified distance of a single location. The Distance to many locations option allows you to target site visitors who are within a specified distance of one of many locations. You can adjust both to target people who are within or not within a specified distance of one location (for Distance to location) or many locations (for Distance to many locations).
The location list you upload to Content Manager must meet a few requirements.
The list must be a CSV file that uses UTF-8 character encoding and without the byte order mark (BOM).
You can better ensure the file meets this requirement by opening it in a spreadsheet application and then taking the necessary steps within the application to save it with Comma Separated Values (.csv) set as the format. This screenshot shows an example of one application's Save As modal with the CSV format selected.
You can use any spreadsheet application to create and edit the locations list so long as you save it in the CSV format with UTF-8 character encoding.
The file must have a header row that contains all required fields. You can include permitted optional fields so long as all the required headers are present. While the file can contain additional fields that are neither required or permitted, the platform ignores them during the upload process.
The following list contains all the required headers. Each must appear exactly as shown.
internal_id— The unique identifier for this particular location, which can be any combination of letters and numbers
name— The business or business location name
address1— The first line of the location's physical street address
city— The city where the location is
region— The location's state or province
postal_code— The location's ZIP code or postal code
country— The location's country
Here are a few additional notes about some of the required headers:
- You can use either the postal abbreviation or the full name of the state or province in the
postal_codefield doesn't have a minimum or maximum number of numerals or letters it can contain, and the platform doesn't validate the content.
- If you change the existing internal ID for a location in an update, the platform treats the new ID as a new location.
- The platform doesn't validate any address you upload.
In addition to the seven required headers, you can include any of these optional headers in the locations list file:
address2— The second line of the location's physical street address, if necessary
phone— The telephone number for the location
latitude— The location's north-south geographic coordinate
longitude— The location's east-west geographic coordinate
description— A few words about the location, such as
Inside Mall of America
img_src— The source code for an image file associated with the location, such as
url1— The primary URL associated with the location
url2— A secondary URL associated with the location
tags— Any tags associated with the location, each separated by a vertical pipe character (|), such as
Bloomington retail outlet | Mall of America | Distribution Center
If you do not include a location's latitude or longitude when those headers are present in the file, then the platform uses Google to fetch them when processing the file. If Google cannot find the coordinates, then a message appears on the Locations tab notifying you of the temporary error finding the coordinates. See 'Temporary error geocoding' Message in the troubleshooting section of this documentation for more information.
Uploading a Locations List
Follow these steps to upload the locations list.
- Click COMPONENTS in the top navigation bar, and then select Content.
- Click the Locations tab and then click UPLOAD CSV FILE.
- Follow the prompts to navigate to the location of the CSV file, select it, and then upload it to the platform.
Once the upload is complete, a message stating as much appears above the table.
Ensure you check the COORDINATES column of the table to verify that each location has the necessary longitude and latitude coordinates. If Google must provide the information because you did not, a message appears in the COORDINATES field for each location for which Google is still collecting the coordinates.
If ultimately Google cannot determine the coordinates, then an message about the geocoding failure and the number of locations without coordinates appears above the table.
See 'Temporary error geocoding' Message in the troubleshooting section of this documentation for more information.
Here are some common causes of upload error messages:
- The filename contains one or more spaces or special characters. Remove them.
- The content of one or more fields contains a comma but is not enclosed in double quotation marks. You must put a set of double quotation marks (") at the beginning of and at the end of the content of a field if that content includes a comma (for example,
"Bldg 2, Ste 29"in the
address2field for a location) so that the comma is not mistaken as separating two values. For example, the string
SPJ Publishers,428 Main Stcontains the values for the
address1fields, each value separated by a comma in this comma-separated values (CSV) file.
- The content of one or more fields contains special characters. Remove them.
- The file is not in the CSV format, does not have UTF-8 character encoding, or includes the byte order mark (BOM). Open the file in a spreadsheet application to ensure it is in the CSV format with UTF-8 character encoding and without the BOM.
'Header is missing required fields' Error
The message shown in this screenshot appears if the file you uploaded didn't contain all seven of the required headers or any required header contains a typo.
Resolve the issue by opening the file in a spreadsheet application and then adding the missing required header and the pertinent information for each location or correcting the typo(s) in the header(s). Save the revised file and upload it again.
'Temporary error geocoding' Message
The message shown in this screenshot appears along with the successful upload message because even though the CSV file uploaded successfully, Google couldn't obtain the longitude and latitude coordinates for any location that was missing that data in the file only when the file includes the
longitude optional headers.
Follow these steps to correct this error.
- Click the Locations tab of Content Manager, and then click DOWNLOAD EXISTING CSV.
- Open the file in a spreadsheet application, find the row for the location missing the coordinates, and then verify that all parts of its address are correct. Repeat this step for each location missing coordinates as necessary.
- Load Google Maps in a browser.
- Copy and paste the location's address into the search box, and then click the magnifying glass icon.
- Right-click the pin icon marking the location on the map, and then click the coordinates that appears at the top of the contextual menu to copy them to the clipboard.
- Paste the first number of the pair into the location's
latitudecell, and then paste the second number into the
longitudecell. Save the changes to the CSV file.
- As necessary, repeat steps 4 through 6 for each location missing its coordinates, and then close the file.
- Return to the Locations tab of Content Manager, select Partial Upload Only, and then click RETRY NOW to upload the revised file.
So long as you made no mistakes when copying and pasting the latitude and longitude coordinates from Google Maps into their respective fields in the CSV file, the platform will update the table with the additional coordinates information and display the successful upload message.
Unexpected Results When Updating the List
You may update the locations list for these reasons:
- Add locations
- Remove locations
- Add tags
- Remove tags
- Update a location's information
When you upload a revised CSV file, the platform compares the values for each location as defined by the value of
internal_id in that file to the existing values for each existing location and then updates the list accordingly:
- If the values for a location in the file match the values for a location in the platform, then no changes are made.
- If any value for a location in the file differs from the value in the platform, then the value in the file overwrites the value in the platform.
- If the file does not include a location that is in the platform, then that location is removed from the platform.
- If the file includes a location that is not in the platform, then that location is added to the platform.
To better ensure the update you aim to perform ends with the results you expect, download the most recent file uploaded to the platform and revise it rather than revising a file you have stored elsewhere. This method can at least ensure you're working with the same data the platform contains for the locations in the list.
Unexpected Impact to Experiences When Updating the List
Updating the location list can impact active experiences because the data changes can expand or contract the targeted audience that can subsequently, depending on the circumstances, benefit your company or skew the experience results.
Perhaps the update added the
retail tag to more locations. Meanwhile, an ongoing experience uses the WHO target Distance to many locations configured to show a different landing page to those site visitors within 100 miles of any location tagged
When more list locations gained the
retail tag, the active experience could consequently target more site visitors who are within 100 miles of the larger pool of locations with the
Consider another example. You need to update the latitude and longitude for your company's lone retail location in San Francisco because it moved to a larger space 10 blocks away. However, an active experience just so happens to target customers based on their distance from the San Francisco store.
In this type of situation, you can update the location list with the new address and geographic coordinates for the San Francisco store while the experience is running. Next, pause the experience, duplicate it, and then activate the duplicated experience. If you do not start a new experience, the original experience continues, still using the outdated latitude and longitude coordinates.