Data Import Developer Guide

The Google Analytics Management API enables programmatic access to the Data Import feature of Google Analytics.


The Management API allows you to upload, list, delete and get uploaded files as well as list data sets. For a high level overview of the benefits of the Data Import feature see the About Data Import Help Center article.

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 the data sets 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 data set.

Use Cases

The data import feature has three top level categories, each with its own use cases. The organization is as follows:

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 Google Ads remarketing audiences for your most valuable user segments.

To learn how to import user data into Google Analytics to create Google Ads remarketing audiences, see:

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 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 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 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:importBehavior 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

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

Header Constraints

  • The first row is considered a column header and is required. It must define the dimensions and metrics 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.