How to send data to Google Analytics in Python with PyGAMP

PyGAMP allows you to insert data into Google Analytics using the Measurement Protocol API in Python. Here's how you can use it.

How to send data to Google Analytics in Python with PyGAMP
Picture by Serpstat, Pexels.
11 minutes to read

The Google Analytics Measurement Protocol API lets you add data to your GA account that hasn’t been triggered by a user visiting a web page. Since it’s so flexible, you can use the Measurement Protocol to import almost any kind of data into your GA account, from orders taken offline in a shop, or on marketplaces such as eBay and Amazon, to customer-specific metrics for use in custom paid search audiences.

How it works

While the Measurement Protocol API is fairly straightforward to use, you do need to carefully construct the “payload” you pass to the API’s “endpoint” in order for things to work as expected. To make this easier, I created a simple Python package called PyGAMP to handle it. Here’s how to use it. This currently supports the following features of Google Analytics Measurement Protocol:

  • App screenviews
  • Exceptions
  • Pageviews
  • Event tracking
  • Social interactions
  • Custom dimensions
  • Custom metrics
  • Ecommerce tracking
  • Enhanced ecommerce tracking
    • Internal promotions
    • Item and transaction refunds
    • Checkout options
    • Checkout steps

Install PyGAMP

First, open a Jupyter notebook and install my PyGAMP package using pip3 install pygamp, then import pygamp as pg and uuid. No credentials are required. You can import data into any Google Analytics account using just the tracking ID parameter, which is often visible of the source code of the page itself. The tracking ID will look like this: UA-123456-1.

import pygamp as pg
import uuid

Open Realtime reporting in Google Analytics

When you insert new data into Google Analytics there is a delay between the data being sent and its appearance within your main reports. However, you can see the data via the Realtime reports section of the GA interface a second or time after they hit GA.

Set up PyGAMP

Irrespective of the data you want to push to Google Analytics, you’ll require two things: a Universal Analytics property ID, and a client ID. The property ID, i.e. UA-123456789-1, defines the account you want to push your data into. The client ID “pseudonymously” identifies a user, device, or browser, and is stored in a first-party cookie.

The client ID uses the random UUID v4 format and looks like this: 35009a79-1a05-49d7-b876-2b884d0f825b. Specific client IDs can be extracted from the user’s cookie and stored in your database, allowing you to associate data that you push into GA with a specific user. However, in most cases you can just create a random UUID and push the data in with this. I’d suggest setting these up and assigning them to variables.

client_id = str(uuid.uuid4())
property_id = 'UA-123456789-2'

Pageviews

To make it clearer what each of the function arguments refer to I have added their names, but you don’t need to do this in your production code, unless you want to. To send a pageview, we can call pageview() and pass in the cid and property_id, and then include the document_path, document_hostname, and document_title.

pg.pageview(
    cid=client_id,
    property_id=property_id,
    document_path='/hello',
    document_hostname='example.com',
    document_title='Hello'
)

Social interactions

The social() function allows you to insert social interaction data into Google Analytics. This requires a social_action, such as like, the social_network, i.e. facebook, and the social_target.

pg.social(
    cid=client_id,
    property_id=property_id,
    social_action='like',
    social_network='facebook',
    social_target='/home'
)

Promotions

Data on promotions can be added using the promotion_impression() and promotion_click() functions. These take a range of arguments defining the type and position of the promotion to record when each one was viewed and clicked.

pg.promotion_impression(
    cid=client_id,
    property_id=property_id,
    document_hostname='example.com', 
    document_path='about-us', 
    document_title='About us', 
    promotion_index=2, 
    promotion_id='PROMO1', 
    promotion_name='Summer sale', 
    promotion_creative='Summer', 
    promotion_position='Slot 1'
)
pg.promotion_click(
    cid=client_id,
    property_id=property_id,
    promotion_index=2, 
    promotion_id='PROMO1', 
    promotion_name='Summer sale', 
    promotion_creative='Summer', 
    promotion_position='Slot 1'
)

Events

Events are perhaps the most useful feature in the whole of Google Analytics and let you record pretty much anything you like. They’re commonly used for tracking things like the products added to baskets, users filling in forms, and loads of other things. They’re easily created using the event() function.

pg.event(
    cid=client_id,
    property_id=property_id,
    category='Products',
    action='Added to cart',
    label='XYZ',
    value=3,
    non_interactive=0
)

Custom dimensions

Custom dimensions are one feature that definitely does need to be used with the actual client ID of the user, since they associate data to that individual within Google Analytics. For example, you might extract the client ID from the GA cookie, store it in your database, and then calculate customer-specific metrics via a model and then push the data back into GA.

pg.custom_dimension(
    cid=client_id,
    property_id=property_id,
    index=2,
    value='Analytics'
)

Custom metrics

Similarly, custom metrics are associated with specific individuals, so need to be used with the user’s specific client_id in order to work correctly. As with custom dimensions, these map to the index of a specific metric that has already been created in GA.

pg.custom_metric(
    cid=client_id,
    property_id=property_id,
    index=2,
    value='99.99'
)

Transactions

If you have retail premises, or take orders via marketplaces such as Amazon and eBay, and you want to add these orders to your Google Analytics account, you can use the enhanced_transaction() function to push the data in. To do this, the first step is to create a dictionary (which I’ve called basket) which contains the data on the products you want to add.

basket = {
    1: {'product_id': 'ABC1',
        'product_name': 'Product 1',
        'product_price': 19.99,
        'product_quantity': 1,
        'product_brand': 'Apple',
        'product_category': 'Phones',
        'product_variant': '256GB',
        },
    2: {'product_id': 'ABC2',
        'product_name': 'Product 2',
        'product_price': 20.99,
        'product_quantity': 2,
        'product_brand': 'Apple',
        'product_category': 'Phones',
        'product_variant': '500GB',
        },
    3: {'product_id': 'ABC3',
        'product_name': 'Product 3',
        'product_price': 39.99,
        'product_quantity': 3,
        'product_brand': 'Apple',
        'product_category': 'Phones',
        },
}

Next, we can use the enhanced_transaction() to push in the data on the transaction, along with the basket dictionary containing the details on the items within.

pg.enhanced_transaction(
    cid=client_id,
    property_id=property_id,
    document_hostname='example.com', 
    document_path='/order', 
    document_title='Order complete', 
    transaction_id='12345', 
    transaction_revenue=199.99, 
    transaction_tax=40.00, 
    transaction_shipping=0.00, 
    transaction_coupon='SALE', 
    items=basket)

Refunds

Refunds can also be processed in Google Analytics using PyGAMP. These can either be done at the transaction level using refund_transaction() or at the item level using refund_items(). This allows you to remove any refunded transactions or items from your data, so your marketing team don’t get a false impression on what revenue was generated.

pg.refund_transaction(
    cid=client_id,
    property_id=property_id,
    transaction_id='124698938'
)
pg.refund_items(
    cid=client_id,
    property_id=property_id,
    transaction_id='124698938',
    item_code='XYZ1',
    item_quantity=1
)

Exceptions

Exceptions, such as application errors or site issues, can be recorded in Google Analytics using the exception() function. This takes an exception_description argument stating the name of the exception, and an integer value in exception_fatal which is set to 1 on fatal exceptions or 0 on non-fatal exceptions.

pg.exception(
    cid=client_id,
    property_id=property_id,
    exception_description='Payment error',
    exception_fatal=0
)

Screenviews

Another app specific feature is the screenview, which can be pushed in using the screenview() function. While these are designed for mobile apps, there’s no reason why you should use them to monitor data science applications, such as models.

pg.screenview(
    cid=client_id,
    property_id=property_id,
    app_name='Angry Birds',
    app_version='1.0',
    screen_name='Home',
    app_id='1234',
    app_installer_id='Apple'
)

Matt Clarke, Friday, March 12, 2021

Matt Clarke Matt is an Ecommerce and Marketing Director who uses data science to help in his work. Matt has a Master's degree in Internet Retailing (plus two other Master's degrees in different fields) and specialises in the technical side of ecommerce and marketing.