Google Analytics Reporting API Announces Version 4

April 20, 2016

Earlier this month Google Analytics announced version 4 of their Reporting API. While version 3 of the API is still supported, all new development and features will be geared towards improving the newest version.

The API v4 features exciting new features, which will bring some of the functionalities that have only been available inside the Google Analytics UI to your custom applications, scripts, dashboards, etc.

Querying Dimensions and Metrics

Just as in the previous versions, you will need to select a valid combination of Google Analytics Dimensions and Metrics. The response looks a lot like a typical “flat table” in custom reports.

Metric Expressions – Calculated Metrics

Beside querying the standard metrics, the new API lets you query for metrics that are a combination of existing ones. This is something that you were able to do in previous versions in the code on your own end—the difference is that Google Analytics will now take the burden of processing those calculations and provide you with new metrics. To get some ideas about creating new metrics take a look at  25 Calculated Metrics for Google Analytics. Our own Charles Farina gives some excellent examples.

Multiple Date Ranges

The multiple date range functionality allows API users to query for two or more different date ranges in the request itself. Same as with metric expressions, this is something that anyone was able to do before in their code once the query response came through. The difference is that API can now take the burden of processing some of the data and provide you with a clean response of comparisons of different dates.

Using a Custom (not predefined) Segment

The new API also allows you to build segments on the spot. Unlike with version 3, where you were only able to use ids of existing segments built inside the UI, you can now define segments inside the query. This functionality is a big improvement. Complicated segments such as the ones using sequencing cannot be replicated on client side.


Second dimension can now serve as a pivot for the response table. This is a very welcomed improvement from v3, where querying multiple dimensions would quickly end up in a big fragmentation and too many rows in the response object.

Histogram Buckets

Histogram buckets is another feature in line of “Google will do the processing on their end so you do not have to.” Putting values in buckets is possible for numeric dimensions such as:

  • Session Count – Example: bucket users in groups where where session count is between 0-3, 4-7, 8+
  • Time Dimensions – Example: bucket sessions in morning, midday, afternoon, evening and night
  • Days Since Last Session
  • Custom Dimension
  • More


And finally, cohorts are now available in API. At the moment the only valid type of cohort is “first visit date.” Cohorts can be observed by day, week, or month. Dimensions and metrics available for cohorts can be found here.

Official documentation for Google Analytics Reporting API v4 can be found here.

Metadata API

There has also been an update to the Metadata API. The API has been enriched with an attribute that lets you know in which version a metric or dimension was added. The (only) json response of the API can be found here. New dimensions and metrics added in v4 are all related to cohorts with exception of  user acquisition campaign, medium, source and channel.