This project is looking for maintainer(s).
For now only pull requests of external contributors are being reviewed, accepted and welcomed. No more bug fixes or new features will be implemented.
If you are interested in giving this project some ❤️, please comment on this issue: #9
Google Analytics API access, with automated concurrency limiting and optional request caching.
npm install ga-api --save
- Concurrent requests limiting (GA allows 10 by default, and we retry on 403s)
- Caching of requests (optional and configurable)
- Loosely based on this.
Note: you'll need to setup a google service account here: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount in order to use this library, and have access to google analytics reporting.
Before using the library, setup the google service account as described in the link, then grab the following information:
- clientId: "[CLIENTID].apps.googleusercontent.com"
- email: "[CLIENTID]@developer.gserviceaccount.com" - you must add a service email here, for the correct view.
- key: "[PATH/TO/PRIVATE.KEY.FILENAME].pem", as described here
- ids: The view ID(s), eg: "ga:[VIEWID]"
You can find the client ID and Email in the google developers console here (after creating it):
And the view ID in the google analytics console here:
So you end up with something like:
var options = {
clientId: "clientidisalongandseeminglyrandomstringofcharacters.apps.googleusercontent.com",
email: "clientidisalongandseeminglyrandomstringofcharacters@developer.gserviceaccount.com",
key: "google-service-private-key.pem",
ids: "ga:12345678"
};
gaApi(args, callBack, settings)
Where:
- args - all the authentication settings plus query parameters
- callBack - a function that can take an
error
and aresult
argument - settings - an optional settings object where you can override the default settings
- startDate - (YYYY-MM-DD), eg: 2015-05-21
- endDate - (YYYY-MM-DD), eg: 2015-05-28
- metrics - any metric to include, eg: "ga:session"
- filters - any filtering you wnat, eg: "ga:pagePath=~/Home"
- dimensions - any dimensions you like, eg: "ga:source"
- maxResults - maximum number of results to return, eg: 100
- startIndex - offset to start from to allow paging, eg: 1, 101
- sort - what to sort by, eg: "ga:source"
The args must also include the Authentication information from above, ie: clientId, email, key and ids.
This function receives an error object and the resulting data from your query, i.e:
function(error, result) {
if(error) throw error;
// Do something with result here
}
The settings can optionally override some deafult settings, these include:
- cache - time in ms for caching requests, default is 0, ie: no cache
- cacheDir - directory to save the cache - uses system temp dir by default (process.env.TMPDIR)
- concurrentLimit - maximum concurrent requests - default is 10 (which is what Google set by default)
- concurrentDelay - how long to delay if we get a 403 error, default is 1000ms
- concurrentMaxRetry - how many times to retry after a 403 error - default is 3
var options = {...authentication info from above...},
gaApi = require('ga-api');
gaApi(_.extend({}, options, {
startDate: "2015-06-03",
endDate: "2015-06-10",
dimensions: "ga:affiliation,ga:date",
metrics: "ga:revenuePerTransaction"
}), function(err, data) {
console.log(data);
});
The resulting data will look something like this:
{ kind: 'analytics#gaData',
id: 'https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXXXXXX&dimensions=ga:affiliation,ga:date&metrics=ga:revenuePerTransaction&sort=ga:affiliation&start-date=2015-06-03&end-date=2015-06-10',
query:
{ 'start-date': '2015-06-03',
'end-date': '2015-06-10',
ids: 'ga:XXXXXXXX',
dimensions: 'ga:affiliation,ga:date',
metrics: [ 'ga:revenuePerTransaction' ],
sort: [ 'ga:affiliation' ],
'start-index': 1,
'max-results': 1000 },
itemsPerPage: 1000,
totalResults: 32,
selfLink: 'https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXXXXXX&dimensions=ga:affiliation,ga:date&metrics=ga:revenuePerTransaction&sort=ga:affiliation&start-date=2015-06-03&end-date=2015-06-10',
profileInfo:
{ profileId: 'XXXXXXXX',
accountId: 'XXXXXXXX',
webPropertyId: 'UA-XXXXXXXX-2',
internalWebPropertyId: 'XXXXXXXX',
profileName: 'Web data',
tableId: 'ga:XXXXXXXX' },
containsSampledData: false,
columnHeaders:
[ { name: 'ga:affiliation',
columnType: 'DIMENSION',
dataType: 'STRING' },
{ name: 'ga:date', columnType: 'DIMENSION', dataType: 'STRING' },
{ name: 'ga:revenuePerTransaction',
columnType: 'METRIC',
dataType: 'CURRENCY' } ],
totalsForAllResults: { 'ga:revenuePerTransaction': '123.456' },
rows:
[ [ 'SOURCE1', '20150603', '12.34' ],
[ 'SOURCE1', '20150604', '56.78' ],
[ 'SOURCE2', '20150603', '90.12' ],
[ 'SOURCE2', '20150604', '34.56' ],
[ 'SOURCE3', '20150603', '78.90' ],
[ 'SOURCE3', '20150605', '12.34' ],
}
So essentially the "rows" attribute of the data object will have what you want.
Note: See this page:https://ga-dev-tools.appspot.com/query-explorer/
for examples of how to use dimensions and metrics and create a report, and:
https://developers.google.com/analytics/devguides/reporting/core/dimsmets
for examples of dimensions and metrics