How to use the Google Analytics Embed API: guide & examples

When I started at Measurelab, way back in July, one of the items on my List Of Things To Do was to look into new and exciting ways of visualising data for clients. A few weeks ago I spent some time experimenting with

dc.js

but then, Mark and Dara went to MeasureCamp in London (I was going to go but I had other commitments) and came back bearing glad tidings of great joy for all analytics consultants, because unto Google, in the town of Mountain View, was born an API, and the angel Justin Cutroni said to call it Embed.

So, there's a new! exciting! JavaScript library in town that allows you to Embed (see, that’s its name!) charts and tables from Google Analytics of the kind that you’d find in custom dashboards onto third-party sites. It’s interesting – quite new, with a few rough edges and still rather scant documentation, and after having spent the week playing around with it, I’ll try and outline some of the good stuff, some of the not-so-good stuff, and why you should care. Let’s go with that first, actually.

Why is this exciting? There are clear advantages for both us and our clients. We can build branded dashboards on our own site, complete with our logo, and still track the data. We also gain more flexibility for visualization: you can use third‑party chart libraries or the standard Google charts. This makes dashboards cleaner and more manageable than the old “export to spreadsheet and draw charts manually” method. Additionally, you can view the same chart using different data views, and even compare multiple views side‑by‑side.

The demo site showcases a lot of the site’s features. If you want to have a look at my efforts so far, I've made a little example dashboard that you can find over here.

The dashboards I made were mostly based the ‘pure HTML’ Polymer.js framework from the sixth example page. I was mostly trying to recreate client dashboards, but I threw together a few other things. The construction process is remarkably simple – you can just plug in the various components, adjusting them to your needs, and go. A few modifications are required here and there, but with a little effort (and judicious appropriation of resources from the demo site) you can have something up and running very quickly. An easy-ish guide follows:

How-to

(this is for non-experts, if it seems insultingly easy, you probably don’t need it)

First up, grab the code from the Github page. You’ll also need an OAuth2.0 client ID from Google – instructions are here and seem to be for an older version of the Dev Console site – but as long as you create a new project, enable the Analytics API and generate new client ID credentials (remember to use http://localhost:8888/, or wherever you’re hosting it as the Authorised Javascript Origin (though if you’ve got a dev server or something you probably don’t need me to tell you this) you should be fine. Copy the contents of the “site” folder into a folder in your MAMP host directory (or whatever you’re using). Open any of the numbered html files in a text editor, substitute your client ID for the one listed, and have a play around. You’ll need to add the folder path to the asset references before you try to load the pages, but once you’ve done that the pages should work fine. I’d recommend getting the early pages working, and once you’ve got things working, have a look at 6, which has a very clear format that you can easily tweak to create the sort of dashboard you need. The components reference the core reporting API, so as long as you're familiar with that (which you will be if you've made much use of the GA spreadsheet addon), you should have no problem.

Things I can’t find written anywhere:

• Despite saying it can’t (under ‘possible options’ in the chart.type string here you definitely can use other kinds of charts – f’rinstance, I made a pie chart by setting chart type to PIE, which it doesn’t say you can do but it turns out you can. Experiment, and see what other unlisted chart types are possible!
• As far as I can tell, you can’t have more than 10 widgets on a page. This is a little annoying, because one of the reasons I was so excited about Embed was not having to split client’s dashboards over multiple pages. I can’t find anything about this in the documentation, so I’m not sure exactly what’s going on there.

My To-Do list

• Get third-party visualisations working
• prettify
• I’m also quite interested to see whether I can pull data from the Management API, because that’s something else that’s been on my R&D research list for a little while (though I haven’t yet had the chance to do it)

Have any of you had a chance to look at the Embed API yet? Maybe butted up against the same 10-widget-on-a-page limit as I did, or have come up with your own novel implementation? Comments and links below would be welcome!