Using the Google Analytics Core Reporting API from Node.js

This blog post explains how to use the Analytics Core Reporting API by Google from Node.js.

Let’s use that API to create a Node.js script analytics.js that downloads the top 10 most visited pages of your website.

Preparations  #

You must first make sure that you can access the Google Analytics API from the script and that the appropriate library for doing so is installed.

Unlocking the Google Analytics API  #

Go to the Google Developers Console:

• Create a new project (e.g. myproject).
• In section “APIs & auth → Credentials”, execute “Add credentials → Service account”.
  • Download the resulting JSON file (e.g. “myproject-3126e4caac6a.json”).
  • Put that file into a directory node_modules that is inside one of the parent directories of the script that we’ll create later. That means that you can keep it out of the repository with analytics.js. For example, the following path is perfectly fine:

    $HOME/node_modules/myproject-3126e4caac6a.json
    

• The credentials that you created have an email address (which is displayed in the user interface and stored inside the JSON file). Copy that email address.

Go to the Admin panel in Google Analytics:

• Analytics has three scopes:
  • Account
  • Property
  • View
• Create a new user in scope “Property”, via “User Management”.
  • That user has the email address that you copied previously.
  • Its permissions are “Read & Analyze”.
• In scope “View”, go to “View Settings” and write down the “View ID” (e.g. 97675673) for later.

Installing the Google API client library  #

• Google provides many public APIs. You need the “Analytics Core Reporting API”.
• All APIs are accessed via the Google API client library. You want the one for Node.js, which can be installed via npm:

  npm install --save googleapis
  

The script  #

The first line of the script enables us to execute the script directly on Unix systems (if it is executable):

#!/usr/bin/env babel-node

The code shown in this section is ECMAScript 6, which is why we run the script via babel-node. You can also omit this first line and run the script like this:

babel-node analytics.js

Next, we import the Google API client library.

import google from 'googleapis';

Next, we import the key and define the view ID (prefixed with 'ga:'):

import key from 'myproject-3126e4caac6a.json';
const VIEW_ID = 'ga:97675673';

Next, we authenticate (consult “Authorizing and Authenticating” for more information):

let jwtClient = new google.auth.JWT(
  key.client_email, null, key.private_key,
  ['https://www.googleapis.com/auth/analytics.readonly'], null);
jwtClient.authorize(function (err, tokens) {
  if (err) {
    console.log(err);
    return;
  }
  let analytics = google.analytics('v3');
  queryData(analytics);
});

Finally, we make the query (for consistency’s sake, all keys are quoted):

function queryData(analytics) {
  analytics.data.ga.get({
    'auth': jwtClient,
    'ids': VIEW_ID,
    'metrics': 'ga:uniquePageviews',
    'dimensions': 'ga:pagePath',
    'start-date': '30daysAgo',
    'end-date': 'yesterday',
    'sort': '-ga:uniquePageviews',
    'max-results': 10,
    'filters': 'ga:pagePath=~/ch_[-a-z0-9]+[.]html$',
  }, function (err, response) {
    if (err) {
      console.log(err);
      return;
    }
    console.log(JSON.stringify(response, null, 4));
  });  
}

We retrieve the top 10 most visited pages within the last 30 days:

• metrics: what was measured?
• dimensions: what meta-data are we interested in?
• Dates: we must provide both a start and an end date. If we want the earliest possible start date (minus infinity, if you will), we can use '2005-01-01'.
• sort: comma-separated keys of either metrics or dimensions.
• filter: we filter the ga:pagePath via a regular expression, so that only files with specific names are shown in the results. The property value is an ES6 tagged template, which is why we can use the backslash directly, without escaping it.

More information on the Analytics Core Reporting API:

• A general overview of the Core Reporting API
• Documentation on the query parameters (the keys in the object object handed to analytics.data.ga.get())
• Common queries, which demonstrate how to use the keys documented by the previous item.