npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

node-simple-ga

v0.5.1

Published

A simple to use NodeJs package for the Google Analytics Reporting API

Downloads

302

Readme

Simple Google Analytics client for NodeJs

It should be much easier to retrieve data from the Google Analytics API and this package helps you achieve that. Focus on analyzing the data let it handle the rest.

This is still very much work in progress so please check back.

Note: Recent v0.3.0 update removed the need to manually create filter objects. Please see the demo.

Down to business

Getting the top 10 links is as simple as this:

var analytics = new SimpleGA("./key.json");

var request = Request()
	.select("pagepath","pageviews")
	.from(12345678)
	.orderDesc("pageviews")
	.results(10);
	
var data = await analytics.run(request);

By default, data will be returned as an array of objects in the format below. For the top 10 list the result would look similar to this:

[
	{
		pagePath: "/",
		pageviews: 123
	},
	...
]

What it really is

node-simple-ga helps you create and make Reporting API v4 compliant JSON requests in a function-oriented manner, parse the response, and paginate additional requests if requested by the user. Further improvements will be focused on creating requests in a more robust and efficient way.

What it won't be

This package is not and will not be a data processing package. Data processing is left up to you - the developer.

Installation

To use the package, run:

npm i node-simple-ga

Before using the package, you must create and set up a Service Account. You can also watch a video tutorial on how to set up a Service account. While the title says it's a PHP tutorial, it doesn't really matter because you won't be using PHP anyway. Focus on the account creation and granting read access to the service account.

Usage

Typical usage for the script follows the following script:

  1. Require node-simple-ga
  2. Initialize the analytics package by providing a valid service account key (see Installation)
  3. Create a request object
  4. Add metrics and dimensions
  5. Add filters
  6. Specify the sort order
  7. Run the request

Optionally:

  1. Clone the request object
  2. Make changes to the request object
  3. Run the request

Example

  • Return all pages of two views XXXXXXXX and YYYYYYYY who don't have at least 100 pageviews,
  • Show page urls, pageviews and users,
  • Make sure page url doesn't contain /archive/,
  • Load only those entries that came from the US,
  • Sort results by the amount of users in a descending order
  • Get only the top 100 results from XXXXXXXX
  • For view YYYYYYYY also get the amount of sessions
const {
	SimpleGA,
	Request
} = require("node-simple-ga");

(async function() {
	var analytics = new SimpleGA("./key.json");

	var request1 = Request()
		.select("pagepath","pageviews","users")
		.from(XXXXXXXX)
		.where("pagepath").not().contains("/archive/")
		.where("country").is("US")
		.where("pageviews").lessThan(101)
		.results(100)
		.orderDesc("users");

	var request2 = request1.clone()
		.select("sessions")
		.from(YYYYYYYY)
		.everything();

	try {
		var [data1, data2] = await Promise.all([
			analytics.run(request1),
			analytics.run(request2)
		]);
	} catch (err) {
		console.error(err);
	}
})();

Since it's not possible to use negative lookups in Google Analytics (e.g. urls that don't contain something), you must first look up all urls with the thing you want to avoid and then negate the operation (in this case with .not())

Please note that if you don't specify a date, only the last 7 days, excluding today, will be processed.

If a date range is not provided, the default date range is (startDate: current date - 7 days, endDate: current date - 1 day). Source

Reference

When specifying a dimension or a metric, you don't have to add ga: at the beginning and you may enter it in a case insensitive manner; the system will fix it for you i.e. pagepath becomes ga:pagePath when querying Google Analytics.

Before processing data, you should know the difference between dimensions and metrics. Read more about it here.

Request functions

select(keys), select([keys]), fetch(keys), fetch([keys])

Specify in a case-insensitive manner which dimensions and metrics you're going to need. You can pass both, an array or a list of metrics or dimensions. It's useful if you generate metrics dynamically. However, if you pass a custom key, such as a computed metric, it's up to you to ensure it's written correctly.

select("pagepath","sessions","users")

is the same as

select(["pageviews","sessions","users"])

from(view)

Used to set the View you're going to process. You can only specify one view per request.

where(keys), where([keys])

Which key or keys will be filtered. You can specify multiple keys so that the following filter will be applied to all keys. Note that if you specify multiple keys at the same time, an OR operation will be applied, meaning one of the filters must be true.

where() is followed by either not() and/or one of the operator functions. All operator functions accept multiple values they are applied to all selected keys. For example, if you have specified 2 keys and 2 values in the operator, you'll end up having an OR filter with 4 conditions.

The only exception of the operator functions is the inList() function. All values that are passed in will be passed as an array of strings, since the goal of this function is to determine whether dimension value is in the list. It means that if you specify 2 keys and 3 values in the inList() operator, you'll end up with 2 inList() filters.

All operator functions are found in the section called Operator functions.

whereDimension(key), whereDimensions(keys), whereDimensions([keys])

Which dimension(-s) will be targeted by the filter. If you're using default dimensions, you can use the where() function. Use these functions if you want to target custom dimensions.

whereMetric(key), whereMetrics(keys), whereMetrics([keys])

Which metrics(-s) will be targeted by the filter. If you're using default metrics, you can use the where() function. Use these functions if you want to target a custom metrics.

orderDesc(key)

Which metric or dimension will be sorted in a descending order.

orderAsc(name)

Which metric or dimension will be sorted in an ascending order.

during(dateFrom, dateTo), period(dateFrom, dateTo)

What time frame should results be selected from.

dateFrom and dateTo must be written in the YYYY-MM-DD format, meaning April 24, 2016 must be written as 2018-04-24.

limit(count), results(count)

How many results per page should be returned. If you don't specify the amount of results, everything will be returned.

everything()

Returns all results. Use on a cloned request that has an amount of results specified.

clearFilters()

Removes all filters.

unselect(keys), unselect([keys])

Which keys will be removed from the selection.

clone()

Returns an identical copy of the request object.

Operator functions

not()

Negates current filter

where("pagetitle","dimension10").not()...

is(values), is([values]), equals(values), equals([values])

What must the key value be equal to.

contains(values), contains([values])

What must the dimension value contain.

beginsWith(values), beginsWith([values])

What must the dimension value begin with.

endsWith(values), endsWith([values])

What must the dimension value end with.

inList(values), inList([values])

What must the dimension be equal to.

where("pagetitle","dimension10").inList("apple","orange")

It means that pageTitle or dimension10 must be equal to either apple or orange.

greaterThan(values), greaterThan([values])

What must the key value be greater than.

lessThan(values), lessThan([values])

What must the key value be less than.

matchesRegex(expressions), matchesRegex([expressions])

What regular expression must the dimension values match.

Please note that Google Analytics allows the use of a limited amount of regular expressions. For example, it doesn't allow negative lookaheads, which is why the not() function must be used.

Pagination

Google Analytics API returns up to 10'000 results per request, which means there will be cases when you'll have to make additional requests to get more data. However, this also means you might not need all the data and it can be achieved in two ways: filtering or limiting the amount of pages.

To limit the amount of pages, for example 2 pages (up to 20'000 results, if the result count is not specified), the script will look something like this:

var analytics = new SimpleGA("keyLocation");

// Build the request object
var request = Request()
	...

var data = await analytics.run(request,{pages: 2});

Please note that while it is possible to specify the amount of results and the amount of pages, it is not advised to do so, because you might end up hitting the API limits. For example, if you have specified that you need 10 results and that you need 3 pages, you will end up making 3 requests requesting 10 results per request, which means you will get only 30 results. It's not only significantly slower but it's also wasteful.

It's better to use either results() or specifying the amount of pages.

Transforming results

Version 0.5.0 has the ability to transform the result. For example, if you want to rename the pagePath to url, all you have to do is specify the transformation in the run command.

var data = await analytics.run(request,{
	rename: {
		pagePath: "url"
	}
});

Author

Ringolds Leščinskis

Website: www.lescinskis.com

E-mail: [email protected]