[UA] Custom Data import example

Learn how import and analyze types of data for custom purposes.

Analytics provides a number of import types designed to support specific common use cases. Before you decide to implement Custom Data Import, be sure your use case isn't already covered by one of the other types. Learn more about the types of data you can import.

In this article:


You are engaged in an affiliate marketing program and want to track and analyze your site usage by affiliate traffic segments.

Step 1: Decide what data to import.

For the affiliate marketing example, you might want to import data such as the affiliate's geographic location, and assign categories and types to affiliate-related hits to your site.

Step 2: Create any necessary custom dimensions or Metrics

(Universal Analytics only) If you need to import to dimensions or metrics that are not already provided in Analytics, AND if you have implemented Universal Analytics (analytics.js), then you should create new custom dimensions and/or metrics (e.g. Affiliate ID) and import using them.


To join your imported data with hit data captured by Analytics, you might create an Affiliate ID dimension. You could extract this ID from the query parameters of URLs that send this affiliate traffic to your site.

Step 3: Create the Data Set

A Data Set is a container that holds the data you upload to Analytics. The Data Set schema defines the structure that joins the data you upload with the existing data in your hits. You manage your uploaded data files using the Data Set. Data sets are associated with views, giving you flexibility in how you include imported data in your reports.


To upload the data for your affiliate marketing program, create a Data Set to hold that specific information. The Data Set schema would define a key, perhaps using a custom Affiliate ID dimension and import dimensions for metadata such as Affiliate Geo, Affiliate Category, etc. Then, you can upload affiliate information as needed to that Data Set.

Step Four: Create the CSV

Get the header for the CSV

In the Data Set table, locate the Data Set you created in the preceding step and click its name to edit it.

Click Get schema.

You’ll see something similar to the following:

    CSV header


This is the header you should use as the first line of your uploaded CSV files. The number and naming of the dimensions will vary, depending on your schema definition.

Create a spreadsheet and export it as a CSV

Create a Google spreadsheet that follows the format above. The first (header) row of your spreadsheet should use the internal dimension names (e.g., ga:dimension22 instead of Affiliate ID) provided in the CSV header dialog box in the step above. The columns beneath each header cell should include the corresponding data for each header. In this example, the header consist entirely of custom dimensions, so be sure you know what data each dimension contains. (If necessary, go back and look at the Data Set schema).

ga:dimension22 ga:dimension23 ga:dimension24
A101 Midwest Wine & Food
A101 Pacific Wine & Food
A102 Eastern Sports
A103 Southern Movies, Books and Music

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

    A101,Midwest,Wine & Food
    A101,Pacific,Wine & Food
    A103,Southern,"Movies, Books and Music"

Notice that the last entry in the export uses ASCII quotes around the "Movies, Books and Music" cell. That's because the cell value contains a comma (,) which must be escaped. This should be handled automatically by the export process, but if you are using another process to generate your upload data, be sure to format it as described in the Format upload files article.


Step 5: Upload Data

There are two ways to upload data: manually, using the Analytics web interface, and programmatically via the Management API's Uploads resource.

Step 6: View data in reports

Data you upload using the custom import feature can be included in Custom Reports.


You've uploaded affiliate category data and want to see the total number of pageviews per category. To do this, you would create a custom report with one metric (Pageviews) and one dimension (affiliate category).


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

Real-Time reporting not supported

Real-Time reports do not display imported dimensions.

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