Upload a Locations List

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).

Distance between locations is measured as the crow flies, not in driving distance.

File Requirements

The location list you upload to Content Manager must meet a few requirements.

Format

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.

Example of the Save As modal in a spreadsheet application

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.

Required Headers

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

Be aware of two situations that result in an upload error message:

  • Any required header is missing or contains a typo
  • The country field for any row is empty

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 region.
  • The postal_code field 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.

Optional Headers

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
  • email — The designated email address for the location
  • 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 img src="store76.png"
  • 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 any optional header that you include contains a typo, then any attempt to upload the file results in an error.

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.

  1. Click COMPONENTS in the top navigation bar, and then select Content.

    Callout of the Content option in the COMPONENTS menu

  2. Click the Locations tab and then click UPLOAD CSV FILE.

    Select Partial Upload Only if the file you're uploading adds or removes locations; adds or removes information in tags fields; or updates information for locations already listed.

    Callout of the 'UPLOAD CSV FILE' button on the Locations tab of Content Manager

  3. Follow the prompts to navigate to the location of the CSV file, select it, and then upload it to the platform.

    If the file doesn't include latitude and longitude coordinates, then processing may take a little longer.

Once the upload is complete, a message stating as much appears above the table.

Example of the message stating the successful upload of a CSV file

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.

Callout of the 'Processing. Check back later' message in the COORDINATES column for a location

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.

The Locations tab with the message 'Temporary error geocoding. We made several geocoding attempts but were unable to determine coordinates for 1 location. Please manually retry.'

See 'Temporary error geocoding' Message in the troubleshooting section of this documentation for more information.

Troubleshooting Uploads

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 address2 field for a location) so that the comma is not mistaken as separating two values. For example, the string SPJ Publishers,428 Main St contains the values for the name and address1 fields, 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.

The Locations tab with the message 'Error! The file you uploaded could not be processed. Header is missing required fields.'

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 latitude and longitude optional headers.

The Locations tab with the message 'Temporary error geocoding. We made several geocoding attempts but were unable to determine coordinates for 1 location. Please manually retry.'

Follow these steps to correct this error.

  1. Click the Locations tab of Content Manager, and then click DOWNLOAD EXISTING CSV.

    Callout of the 'DOWNLOAD EXISTING CSV' button on the Locations tab of Content Manager

  2. 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.
  3. Load Google Maps in a browser.
  4. Copy and paste the location's address into the search box, and then click the magnifying glass icon.

    Example of inputting an address into the Google Maps search field

  5. 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.

    Callout of longitude and latitude coordinates at the top of the contextual menu of Google Maps pinned location

  6. Paste the first number of the pair into the location's latitude cell, and then paste the second number into the longitude cell. Save the changes to the CSV file.
  7. As necessary, repeat steps 4 through 6 for each location missing its coordinates, and then close the file.
  8. Return to the Locations tab of Content Manager, select Partial Upload Only, and then click RETRY NOW to upload the revised file.

    Callout of the 'Partial Upload Only' option and the 'RETRY NOW' button

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.

You can only download the most recently uploaded file when you click DOWNLOAD EXISTING CSV. There is no archive of uploaded files for Location Manager.

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 retail.

Callout of the WHO settings of a Web experience configured with the 'Distance to many locations' option and configured to target site visitors within 100 miles of any location tagged 'retail'

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 retail tag.

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.