Using the Google Analytics Cost Data Import Tool

in Google Analytics API

This is the first in a series of posts I'm writing about the GA cost data import tool that allows you to include data in your reports from ad networks other than AdWords. Google Analytics now allows you to measure the performance of the paid ad campaigns you're running on platforms such as Facebook, LinkedIn, and Bing via the cost data import service of the Management API.

In this article I'm going to give an overview explaining how this service works and what options are available. In future articles I'll expand on this with real examples you can use to insert data from your own ad campaigns into Google Analytics.

Overview of the GA Import Tool

The cost data import works by taking a CSV file and matching up the rows in it with the campaigns you're tracking using custom campaign tracking parameters. You download performance reports from your ad network, transform them into the format required by the GA API, then send the transformed files to the API for insertion into your account. Here's the steps you need to follow:

  • Tag the destination URL's of your ads.
  • Download performance reports for your ads and prepare them for import.
  • Create a custom data source for your ad network.
  • Run a script to import the data into the custom data source.

The rest of this post will discuss each of these steps.

Tagging Your Ad Destination URL's

You should already be using campaign tracking parameters, but I'll start by discussing it briefly. To track campaigns other that AdWords in Analytics, you need to add some, or all, of the following parameters to your ads destination URL:

  • utm_source: The name of your ad network.
  • utm_medium: The type of ad you're running, such as CPC.
  • utm_campaign: The logical grouping of your ads.
  • utm_term: The targeting that triggered your ad, such as a keyword.
  • utm_content: The content that the visitor viewed before visiting your site, such as an ad unit.

You should at least tag your URL's with the utm_source and utm_medium parameters; the rest are optional, but will let you perform more fine-grained analysis. Here's an example URL that includes all the parameters:

http://test.ewanheming.com/?utm_source=acme+ads&utm_medium=cpc
&utm_campaign=Kitty+Crunchy+Bites&utm_term=kitten+food
&utm_content=Crunchy+Cat+Treats
Example URL with Campaign Tracking Parameters

For more information about this, see my article on [Tracking Bing Ads in Google Analytics][link-106].

[&link slug="link-106" name="Tagging Bing Ads for Google Analytics" node="track-bing-ads-google-analytics"][&end]

Preparing Reports For Import

The Google Analytics cost data import tool requires a CSV file in a specific format, so you need to process the performance reports you download from the ad networks. You need to create a file for each day's data with columns for each field that you want to include.

There are five columns that correspond to the five parameters you put into your ad URL. The following table shows each parameter, its matching column name, and the data that the column needs to contain to match the example URL I presented earlier:

URL Parameter CSV Column Example Data
utm_source ga:source acme ads
utm_medium ga:medium cpc
utm_campaign ga:campaign Kitty's Crunchy Bites
utm_term ga:keyword kitten food
utm_content ga:adContent Crunchy Cat Treats

The API requires you to supply the source and medium columns, but the rest are optional; you just won't be able to drill-down to the level that you omitted. Once the GA import process has matched a row in the file to a visit from your ad, it then attaches the impressions, clicks, and costs to it using the ga:impressions , ga:adClicks, ga:adCost columns in the CSV file. You must include at least one of these columns, and if you skip a column then it will default to zero. Here's an example showing how the CSV file looks using the columns I've discussed so far:

ga:source ga:medium ga:campaign ga:keyword ga:adContent ga:impressions ga:adClicks ga:adCost
acme ads cpc Kitty's Crunchy Bites kitten food Crunchy Cat Treats 100 10 21.52

In addition to these basic columns, there's more fields that you might want to add for further analysis:

  • ga:adGroup: The ad group that contains your ad.
  • ga:adMatchedQuery: The specific search term that triggered your ad.
  • ga:adSlot: The area of the page where the ad network displayed your ad, such as the “top” and “other” dimensions available for AdWords ads.
  • ga:adSlotPosition: The average position of your ad relative to the other ads on the page.
  • ga:referralPath: The page where the ad network placed your ad.
  • ga:adDisplayUrl: The display URL of your ad.
  • ga:adDestinationUrl: The destination URL of your ad.
  • ga:adwordsCampaignId: The id that your display network uses to identify your campaign.
  • ga:adwordsCriteriaId: The id that your display network uses to identify your targeting options, such as the keyword.

Creating a Custom Data Source

Before importing cost data into Google Analytics, you need to create a Custom Data Source to associate the data with your web properties and profiles: a custom data source is a container for the daily import files and specifies the type of data that the files contain (currently the API only supports cost data) and which profiles should display the data. You can set up a custom data source from the Custom Definitions tab of a web property's admin panel:

Google Analytics Custom Data Source
Google Analytics Custom Data Source

Click on the New Custom Data Source button to add a new source:

Adding a Custom Data Source
Adding a Custom Data Source

First give your custom data source a name and description, then select the profiles where you want to see the data in your reports and press Save; although the Type field has a drop-down, you can't select anything but cost at the moment. Once you click the save button, you'll be taken back to the list of data sources:

GA Custom Data Source ID
GA Custom Data Source ID

You'll see the ID of the data source in the last column, named UID, that you need to record for use in your import script.

Importing the Cost Data into Google Analytics

Once you've prepared the files for import into GA and created a data source, you need to add the data to the data source using a script. This script should make a call to the upload() method of the dailyUploads Management API service. This method has the following parameters:

  • accountId: The ID of the GA account that holds your web-property; you can extract this from the middle of the web-property ID.
  • webPropertyId: The web-property that contains your custom data source; this is the same UA-XXXXX-XX ID that you insert into your tracking code.
  • customDataSourceId: The ID of the custom data source you created earlier.
  • appendNumber: An integer, between one and twenty, for keeping track of the number of times you've appended cost data each day.
  • date: The date of the data in the import file; the API requires one file per day.
  • type: The type of data in the import file; the API only supports cost data at the moment.
  • reset: A flag to tell the API to remove any old data for the date, and start fresh with the data in the import file.

For an example of using this service, you'll need to check the documentation for the Google data client library you're using or check out my next post, which will provide a complete example. For now, I'm going to finish off this article by running through the options for appending, deleting, and overwriting cost data.

Appending to the Cost Data for a Day

You can't import a file larger than 5MB, so you might need to append several files to GA for a single date; you can do this by setting the reset flag to false and incrementing the appendNumber parameter each time you import another file. You can view the number of files you've imported in the upload history:

Appending Data to a Custom Data Source
Appending Data to a Custom Data Source

You can append up to twenty files for each day, but you must make sure you increment the appendNumber parameter each time and finish importing all the files within ten days from the first append.

If you append a file with the same dimensions as a previous file, Google Analytics adds its data to the stats you previously imported; the API will aggregate your data, not override it. So, for example, suppose you import the following file for the 10th April, 2013:

ga:source ga:medium ga:campaign ga:keyword ga:adContent ga:impressions ga:adClicks ga:adCost
acme ads cpc Kitty's Crunchy Bites kitten food Crunchy Cat Treats 100 10 21.52

Then you import a second file for the same campaign, keyword, and ad:

ga:source ga:medium ga:campaign ga:keyword ga:adContent ga:impressions ga:adClicks ga:adCost
acme ads cpc Kitty's Crunchy Bites kitten food Crunchy Cat Treats 20 5 10.01

Analytics will add this data to the previous data, so you'll see the combined total of both files in your reports:

ga:source ga:medium ga:campaign ga:keyword ga:adContent ga:impressions ga:adClicks ga:adCost
acme ads cpc Kitty's Crunchy Bites kitten food Crunchy Cat Treats 120 15 31.53

Deleting the Cost Data for a Day

If you decide you want to remove the data you imported for a date, you can use the delete() method of the dailyUploads service. This method takes the accountId, webPropertyId, customDataSourceId, date, and type parameters and deletes the data for the selected date. You can see that the data has been deleted in the import history:

Deleting Data from a Custom Data Source
Deleting Data from a Custom Data Source

Overwriting the Cost Data for a Day

You can overwrite the previously imported data for a date, without having to delete the it first, by setting the reset flag to true. This will add a reset row to the import history:

Overwriting Data in a Custom Data Source
Overwriting Data in a Custom Data Source

Most of the time, you'll just want to import a single file at the end of each day so it's best to use the reset flag to make sure the import removes any old data before it begins.

Next Steps

In my next post, I'll go through each step outlined here with some example PHP code.

Comments

I'm keen to get feedback on my posts, so if you have any questions or comments, then please send me a message and I'll be happy to help.