Data Import - Developer Guide

This document explains advanced concepts for developers on how to use the Management API to import data to your Google Analytics account.


The Data Import feature in the Management API allows you to upload, list, delete and get imported data for your Google Analytics Account. For an overview and to learn more about the benefits of the Data Import feature, see About Data Import.

The two resources in the Management API that enable Data Import are:

  • The Custom Data Source resource, called a Data Set in the web interface, which acts as a container for your uploaded files. A collection of Custom Data Sources represents all of the data sources associated with a Google Analytics property.
  • The Upload resource which represents an uploaded file. A collection of Upload resources represents all of the files you have uploaded to a Custom Data Source / Data Set.

Before You Begin

All Google Analytics APIs are accessed in a similar manner. Before beginning with the Management API, read:

  • The client libraries page for a complete list of programming language specific client libraries that work with the API.
  • The Reference Guide to learn the API interface to access data without a client library.

Each client library provides a single analytics service object to access all Management API data. To create the service object:

  1. Register your application in the Google Developers Console.
  2. Authorize access to Google Analytics data.
  3. Create an Analytics service object.

If you haven't completed these steps, please stop and read the Hello Google Analytics API Tutorial. This tutorial will walk you through the initial steps of building a Google Analytics API application. Once complete, you will understand how to access Google Analytics APIs to perform real-world tasks.

Use Cases

The Data Import feature can be used to integrate your business data with Google Analytics data. For example, you can use:

Hit Data Import

Refund Data

Ecommerce transactions that have been fully or partially refunded can be uploaded to Google Analytics. This makes it easy to automatically reconcile the data in your Google Analytics ecommerce reports with processed refunds.

To learn how to import refund data into Google Analytics see Refund Data import example.

Extended Data Import

User Data

You can upload non personally identifiable user data from external CRM tools and create AdWords remarketing audiences for your most valuable user segments.

To learn how to import user data into Google Analytics to create AdWords remarketing lists, see Importing User Data to create AdWords Remarketing Audiences.

Campaign Data

You can import campaign data into Google Analytics to customize your campaign performance analysis for your business.

To learn how to import campaign data into Google Analytics, see Importing Campaign Data using the Management API.

Geographical Data

You can import mappings of geographical IDs to regions, allowing reports on Google Analytics data by custom region. For example, in the United States, you might operate in East, Central, and West groups of states; in Europe, you might operate across North, Central, and South groups of countries. When importing data, you can use the ga:regionId, ga:cityId, ga:countryIsoCode , or ga:subContinentCode as keys. The city IDs and country IDs can be found listed in the Geographical Targeting table. The Country ISO Code and Sub Continent Code can can be found listed in the ISO-3166-1 alpha-2 and UN M.49 tables respectively.

For more information on importing geographical data, see the Geographical Data import example.

Content Data

You can upload content-related metadata, such as author and subject, to leverage Google Analytics to do in depth analysis of articles published on a website.

To learn how to import content data into Google Analytics, see Content Data import example.

Product Data

Importing Product Data into Google Analytics simplifies and reduces the amount of ecommerce data you need to send along with hits, like pageviews and events. A single product ID or SKU can be joined with your imported product data to populate product dimensions and metrics in your reports.

To learn how to import your product data into Google Analytics, see Importing Product Data using the Management API.

Summary Data Import

Cost Data

You can upload cost data for non-Google paid campaigns and leverage the Google Analytics platform to perform ROI analysis and compare campaign performance for all online advertising and marketing investments.

To learn how to import cost data into Google Analytics see Importing Cost Data using the Management API.


Processing Status

After you upload a file, the status of the upload will be PENDING until the upload has been validated and processed. If processing is successful, the status will change to COMPLETED.

If an error occurred during processing and the upload was not successful, the status of the upload will be FAILED. A list of errors will be provided to help you identify the problem(s) with the file. The following is an example response for an upload that failed validation:

  id: "YU4DersR_ORzyzXC_AoWw",
  kind: "analytics#upload",
  accountId: "12345",
  customDataSourceId: "poaU7EPcR4WGU-dkNghYKQ",
  status: "FAILED",
    "Invalid cell data 12.99 at row 1 column 6. expected data type LONG.",
    "Invalid cell data 12.99 at row 2 column 6. expected data type LONG.",
    "Invalid cell data 23.81 at row 3 column 6. expected data type LONG.",
    "Invalid cell data 199.99 at row 4 column 6. expected data type LONG."

Cost Data Summation vs Overwrite

When creating a Custom Data Source / Data Set for cost data you have the option to specify how to handle cases where an uploaded file contains a row of data with a key (i.e. date, source, medium) that matches an existing row. The options are:

  • summation (default) - The new data will be added to any previous matching data and the metrics will be summed together.
  • overwrite - The new data will overwrite any previous matching data.

To find out which type has been set for a Custom Data Source / Data Set use the custom data source list method to check if the importBehavior property is set to OVERWRITE or SUMMATION.

Cost Data Row Level Summation vs Overwrite

You also have the option of overriding the Custom Data Source / Data Set behavior for each file you upload by including the ga:importBehavior column in the header. On a row-per-row basis you can set the value of ga:importBehaviour to SUMMATION or OVERWRITE.

For example, the following file will overwrite any previous cost data for Facebook/cpc and Yahoo/cpc, but the row for Bing/cpc will be added to any existing cost data for that particular date and source/medium combination.

ga:date,ga:source, ga:medium,ga:adCost,ga:importBehavior

Data Import Format and Constraints

In order for data to be uploaded to Google Analytics, it must be in a properly formatted CSV file. This section describes those constraints that it needs to satisfy before it can be considered valid for upload to all Data Import types.

If any of the constraints below are violated or if there is a parsing error, the upload request will fail with error message(s). The API will report up to 10 errors in a single response to help users reduce the number of invalid uploads.

File Constraints

  • Encoding: UTF-8
  • File size limit: 1 GB
  • The first row is considered a column header and is required.
  • It must define the dimensions and metrics that that particular column will contain.

Row Constraints

  • There is a row limit of 1 MB.

Cell Formatting

  • Cells can have a maximum length of 2048 characters.
  • Leading and trailing spaces for a cell will be stripped.
  • To specify a comma within a cell, the value of the cell should be inside double quotes. E.g., source1,"medium,ether",group1,100 — The second cell value is medium,ether.
  • To specify double quotes within a cell, in addition to start and end double quotes, escape the double quote with another double quote. E.g., source1,"medium""ether",group1,100 — The second cell value is medium"ether.

Code Examples

The upload resource allows an authorized user to upload, list, get, and delete imported data. The customDataSource resource allows an authorized user to list any custom data sources. To use any of these methods, you need to create an Analytics service object, as described in the Before You Begin section.

For the code examples that show you how to work with the uploads resource visit the following method references.


  • list — Lists upload to which the user has access.
  • get — Get uploads to which the user has access.
  • deleteUploadData — Delete data associated with a previous upload.
  • uploadData — Upload data to a custom data source.

Custom Data Sources / Data Sets

  • list — Lists custom data sources to which the user has access.