[UA] Geographical Data import example

Learn how to import geographical sales regions.

Importing Geographical Data makes it possible for you to organize your data around custom geographical regions that are aligned with your business' organization.

In this article:


Let's say your company's operations are organized around specific geographical sales regions: East, Central, and West. Today, by default, Analytics will only report on default geographical regions. By using the geographical type in Data Import, you can create a mapping between the specific regions you use for your business and the default regions in Analytics. You can then see your data organized around these custom sales regions.

Step One: Decide what data to import

You want to show data grouped into 3 sales regions: East, Central, and West. These regions are defined at the state/province level. An example of this for the United States might look like this:

Example sales regions
State/Province Sales Region
California West
Nevada West
New York East
Connecticut East
Illinois Central
... ...


Step Two: Map your data to a geographical ID dimension

Analytics has 5 geographical ID dimensions, each at a different geographical hierarchy level. In this step, you'll need to identify at which level your business data resides, then you'll need to map your business data to a corresponding geographical ID at that level of the hierarchy.

In our example, we want to map the state of California to the West sales region. Here's how to do that:

  • State is at the region level of the geographical hierarchy.
  • Region corresponds to the geographical ID dimension ga:regionId.
  • In the Geographical Criteria ID table, California has the Criteria ID 21137.
  • So in our table of sales regions, we would map the West region to the ga:regionId 21137.
  • Continuing this process, the state of Nevada is also in our Western sales region, so we add Nevada's Criteria ID of 21166 our mapping.

After mapping all of the regions you will end up with the following table:

Example sales region mappings
ga:regionId Sales Region State
21137 West California
21166 West Nevada
21167 East New York
21139 East Connecticut
21147 Central Illinois
... ... ...


Step Three: Create the custom dimension

Since Sales Region doesn't exist as a dimension in Analytics, you'll need to create it as a custom dimension. Name the custom dimension "Sales Region" and set the Scope to Session.

Note: All custom dimensions that map to geographical dimensions must be configured as session-scoped dimensions.

How to create a custom dimension

You need the Editor role at the property level to create or edit custom dimensions or metrics.

  1. Sign in to Google Analytics.
  2. Navigate to your property.
  3. In the PROPERTY column, click Custom Definitions, then Custom Dimensions.
  4. Click New Custom Dimension.
  5. Add a Name. This can be any string, but use something unique so it's not confused with any other dimension or metric in your reports.
  6. Set the Scope to Session. Read more about scope and how custom dimensions are processed in the Analytics Developer Guide.

  7. Select Active to start collecting data and see the dimension in your reports right away. To create the dimension but have it remain inactive, clear the check box.
  8. Click Create.

Learn more about custom dimensions.


Step Four: Create a Data Set

The Data Set is the container that will hold your imported data. Create a new Geographical Data Set following the example below to hold your mapping of Criteria IDs to sales regions.

How to create a Data Set:

You need the Editor role at the property level to create or edit Data Sets.

  1. Sign in to Google Analytics.
  2. Navigate to your property.
  3. In the PROPERTY column, click Data Import.
  4. Click New Data Set.
  5. Select Geographical Data as the Type.
  6. Enter "Sales Regions" for the Name.
  7. Select one or more views in which you want to see this data.
  8. Define the schema using the example below as a model.
  9. Click Done.


Schema Example

Geographical Data Sets allow you to pick 1 of the 4 available Geographical ID dimensions to use as your key. You must also specify at least one data dimension to import. For this example, select the following:

  • Key: ga:regionId
  • Imported Data: Sales Region (the custom dimension you created in the previous step)
  • Overwrite hit data: Yes

Get the header for the upload file

Before proceeding to the next step, get the Data Set schema to use as your upload file header:

Click Get schema.

You'll see something similar to the following:

CSV header

Your custom dimension will most likely have a different internal name from the one shown here.

This is the header you must use as the first line of your uploaded CSV files. You can copy/paste this into your CSV file directly, or you can click Download schema template to open this in a spreadsheet.


Step Five: Create the upload file

You upload data to Analytics by importing a CSV (comma separated values) file. This will be based on the table defined in Step Two, but must be formatted in a specific way, as described in Formatting upload files.

Create a spreadsheet and export it as a CSV

Create a spreadsheet that contains the data you want to upload (e.g., sales regions) as well as the key values that will join that data to your collected hits (e.g., Criteria ID). The first (header) row of your spreadsheet should use the internal dimension names (e.g., ga:regionId instead of "Region ID", ga:dimension23 instead of "Sales Region"). You can get those internal names by downloading the schema template, as described above. The rest of the spreadsheet should include the corresponding data for each column.

Example spreadsheet data
ga:regionId ga:dimension23
21137 West
21166 West
21167 East
21139 East
21147 Central

Export the spreadsheet as a CSV. Your file will look something like this:



Step Six: Upload the data

There are 2 ways to import data into Analytics: manually, via the user interface, or programmatically, using the Management API.

Upload manually
  1. Sign in to Google Analytics.
  2. Navigate to your property.
  3. In the PROPERTY column, click Data Import.
  4. In the Data Set table, find the row for your Sales Regions Data Set.
  5. Click Manage uploads for the Sales Regions data set.
  6. Click Upload file, select the file, then click Upload.
Upload via the Management API
  1. Sign in to Google Analytics.
  2. Navigate to your property.
  3. In the PROPERTY column, click Data Import.
  4. In the Data Set table, find the row for Sales Regions.
  5. Click the Data Set name.
  6. Click Get Custom Data Source ID…
  7. Make a note of the ID (you will need it for the steps described in the Developer Guide).
  8. Follow these instructions to upload via the Management API.


Step Seven: See the data in reports

Since sales region is a custom dimension, it does not automatically appear in standard reports, but you can add it as a secondary dimension. For example, in the Geo > Location report, you can choose Country as the primary dimension, and then add Sales Region as the secondary dimension. You can also include imported geographical dimensions in custom reports.

Uploaded data needs to be processed before it appears in reports. Once processing is complete, it may take up to 24 hours before the imported data is applied to incoming hit data.


Was this helpful?

How can we improve it?
Choose your own learning path

Check out google.com/analytics/learn, a new resource to help you get the most out of Google Analytics 4. The new website includes videos, articles, and guided flows, and provides links to the Google Analytics Discord, Blog, YouTube channel, and GitHub repository.

Start learning today!

Clear search
Close search
Google apps
Main menu
Search Help Center