What You Should Know About The New GA4 Data API and UA Property API

GA4 Data API vs UA Property API

Their differences, similarities, advantages, and disadvantages; And how you can import your past data.

Google Analytics 4 (GA4) is a new, exciting, and revolutionary version of Google Analytics that lets you access and track events across platforms in one property. It has shaped how we view user data and insights from our websites and applications.

However, it came as quite a surprise to many who used to depend on the previous Universal Analytics. The differences between Google Analytics 4 and Universal Analytics (UA) are diverse and has changed how we query data with its new Google Analytics Data API.

Because there are a lot of buzzes, confusion, and issues caused by this GA4 Data API, we find it crucial to take a deeper look into the API. So, we will focus on the differences, similarities, advantages, and disadvantages of the new GA4 Data API compared with the previous UA Reporting API.

So let’s dive right in!

What is Google Analytics 4 Data API?

The new Google Analytics Data API is a set of protocols and tools that allows you to access and extract your Google Analytics 4 reporting data. Currently, the API is still in its beta version and with limited capabilities. The API also offers no support to the previous Google Analytics versions at this phase, so it is worth noting before building your next production projects.

Key Differences and Similarities: Google Analytics 4 Data API vs Universal Analytics Property API

While the critical differences between the GA4 Data API and the UA Reporting API emanate from the variance between the two analytics platform versions, there are some noticeable differences that you may consider between the two APIs. So, let’s check it out:

Queries

Unlike the previous API, GA4 Data API’s queries do not have parameters with View ID or Property ID. Rather, you simply pass the numeric GA4 property ID over the request URL. This differs totally from the Reporting APIs that require the views (profile) for reporting identification.

For example:

https://analyticsdata.googleapis.com/v1beta/properties/xxxxxxx:runReport 

Where xxxxxxx is your GA4 property ID. If you were transitioning from UA,
your GA4 property is your UA property without the “UA-” prefix.

Core reporting methods

While the Reporting API uses just a single method for the core reporting functionality, there are more methods with the Data API to increase convenience and functionality.

That is, the Reporting API has only getBatch, whereas the GA4 API has four: runReport, runPivotReport, batchRunReports, and batchRunPivotReports.

The syntax for metrics and dimensions syntax

Visible changes in the API schemas for the custom dimensions and metrics are also apparent between the GA4 API and the previous APIs.

The names of the dimensions and metrics, for instance, are not prefixed with ga: like in Universal Analytics API; the new API uses a new syntax for the dimensions and metrics.

  • The lists of dimensions and metrics are currently compatible, but this may change with further updates.
//UA Property API

 "dimensions": [
    {
      "name": "date"
    }
  ]

//Data API

 "dimensions": [
    {
      "name": "date"
    }
  ]

The date range, clauses, and orderBys

The date ranges between the two APIs changed little, except for the number of the date ranges, on a single request. You can request a limit of four date ranges in the Data API, over two in the Reporting API. 

  • What is similar between the two is the date format input as well as the values.

Like the dimensionsFilterclauses and metricsFilterClauses, the new dimensionFilter and metricFilter clauses do the same thing respectively, but you should rewrite them accordingly in the new API.

Last, the ordering structure in Data API has a different structure for the orderBys field, but with a similar functionality as with the Reporting API. 

  • With Data API’s OrderBys specification, you can sort results according to dimensions, metrics, and pivot, but you need to add the direction ordering.
//UA Property API

"orderBys": [
        {
          "fieldName": "ga:sessions",
          "sortOrder": "DESCENDING"
        }
      ]

//Data API

  "orderBys": [
    {
      "metric": {
        "metricName": "sessions"
      },
      "desc": true
    }
  ]

Results for the API requests

Your request results that are returned also come with more changes in their structure. Probably, any changes were made primarily improves consistency and convenience. So let’s look at the summary of the changes:

Structure of results for dimensions and metrics values 

One difference between GA4 API and UA Property API is the results’ structure for the dimensions and metrics values. GA4 Data API has a consistent structure where both the values for dimensions and metrics are both objects. The UA Property API had metrics as an object with array values, while the values for dimensions were just arrays.

//UA Property API

"rows": [
        {
          "dimensions": [
            "Canada"
          ],
          "metrics": [
            {
              "values": [
                "3467"
              ]
            }
          ]
        }

//Data API

  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Canada"
        }
      ],
      "metricValues": [
        {
          "value": "3467"
        }
      ]

Metrics aggregations

Another difference is what has not been included by default in the query results for the metric aggregations. That is, the new API will calculate metric aggregations only if you specify. 

  • The results of this data metrics will be the same, just as you would get with the UA Property API.
//Specifying Data Metrics in Data API

"metricAggregations": [
    "TOTAL",
    "MAXIMUM",
    "MINIMUM"
  ]

Pivot functionality

While you could get the pivot functionality in the batchGet method, the new API supports it through the runPivotReport and batchRunPivotReports. This change has also affected the way we implement them. Now, each row response represents a single cell within a table over the previous UA Property API, where the row response is represented as a complete table line.

Why is GA4 Data API better than the previous UA APIs?

Offers improved cross-platform analytics

Formerly, Google Analytics 4 was branded as Google Analytics App + Web, and as the name implies, you can now monitor your data from both your applications and websites within a single property. In contrast, UA Reporting API did not offer this functionality in a single property.

Consistent data structures

Data structures for both the requests and results make data extraction simple. For example, the results for metrics and dimensions are now of the same data type, as opposed to the data structure in the previous UA reporting API.

Improved filter syntax

The new Data API has significantly changed how we use the filter for metrics and dimensions to offer greater convenience and functionality. With the new syntax, the new parameters like andGroup, orGroup, and notExpression make it easier to chain multiple filters together, which you had to make several requests in the Reporting API to get the same results.

Easy integration with other business applications

Since your Google Analytics 4 data can be accessed programmatically over the API, it allows seamless integration with your favorite business applications. You can use them with other APIs for you to automate complex reporting tasks and perform powerful customizations according to your needs.

Drawbacks of the new Google Analytics Data API

Does Not Let You Access Your Previous Historical Data

When setting up your GA4 account, the setup doesn’t backfill your previous UA data, nor does it offer a new way to do so. Therefore, your GA4 account will collect and display only the data from the day you set it up unless you import it through other means.

Does Not Support Access to Universal Analytics Properties

GA4 Data API does not support access to properties created using UA. If you need to migrate and have access to data in a GA4 property, your application will need an update to work with both the previous APIs and the new Data API. You will have to create a custom dashboard that handles the data between the two APIs, meaning that you need to do the extra work that can take up your time and resources.

Limited Documentation

Documentation is always the bread and butter of our development process. We sometimes hit the rock and need some real research into what went wrong. Since this is a new thing, custom-builds demand a lot of experimentation for our production applications. So, it is a little frustrating when you have little at your disposal just in case anything went amiss.

No Sampling

The new Data API offers bad news to those who like to build their results on sampled data. Now, you cannot access the same functionality you could get with the samplingLevel field in the Reporting API. Therefore, you can only work with reports only from your unsampled data.

Have an Edge To Learn and Adopt

With this new API, a lot has changed. There’s so much to learn and adopt. Given our daily frustrations that give us a few free minutes daily, it can be a veritable nightmare for many to learn and adopt. 

How to Import Data from Universal Analytics to the New GA4 Data API

The new GA4 platform is not the same or compatible with Universal Analytics. While there are some similarities, you cannot import your previous UA data directly into your GA4 account without doing some manipulations. However, while there are some of Google’s migration tools to get you started, they don’t offer a full and seamless migration.

So, the first thing you may want to do is to get your UA data, then convert them to be compatible with GA4. Luckily, there are many data manipulation tools that can help you to import and work on your past data directly. You may also find other tools that do the conversion for you automatically.

You can also check out how you can import your marketing data with our products like Dataslayer for BitQuery and Dataslayer for Google Sheets to see how they can help you.

Otherwise, you can also use both versions concurrently by updating your application with more custom functionality. You can use your previous API to pull out the data and store them for use wherever you like.

Final thoughts on the new GA4 API

Google Analytics Data API allows you to access your user’s event data from your websites and applications. This is a new API, and as with anything new, it often comes with considerable merits and demerits, which we have discussed in this post. 

There are also major improvements for this new API that have added more functionality, thus making it much better than the previous UA property API. More so, the API’s future promises even more.

The API is still young, though, and many other features are not yet well-developed or rather missing. Besides causing usage inconveniences, the API also requires more effort, dedication, and perseverance to learn and understand how these differences affect how you fetch your data.

However, the unique experience of this API can be a wonderful challenge for those who love to dabble and discover the immense possibilities of new technologies.

Leave a Reply

Your email address will not be published. Required fields are marked *