Some time while I wasn't paying attention, Google posted a neat new map gadget to the visualization gallery. It is called "Geomap", and it is the same map gadget used in the Google Analytics web portal. The documentation page is listed at the end of this article.

This gadget also shows up in iGoogle with the name: "Value Map". If you type that in the "search for gadgets" box, it should come up as the first entry (don't search for or use "Geomap" as this finds a non-Google gadget). The gadget renders using Flash, which means no iPhone/iPad support. But where that is not an issue, this gadget provides the best tool for area and point based data mashups. And that's what I'll be demonstrating in this article - both using the iGoogle Gadget and the Visualization API gadget.

Previously, the "Heat Map" was the only Google map gadget. It is image-based and therefore still has its role (eg, on thos iPads). But the Heat Map gadget could only do thematic (region) maps, and only understood a limited region repertoire. The Value Map supports more data regions and also more display view regions (around a hundred).

The data format section of the reference page shows that the gadget supports two formats. Format 1 takes Latitude/Longitude locations and is used in conjunction with setting the Data Display property to "Markers" (or dataMode="markers" in the visualization API). Format 2 takes a region name or code (ISO-3166-2 or MSA) and is used in conjunction with setting the Data Display property to "Regions" (or dataMode="regions" in the visualization API).

The Google Analytics data feed can return metrics segmented either by lat/long or by region, and ShufflePoint queries can be constructed to create the appropriate JSON results. For example, this query:

SELECT
  METRICS ga:pageviews ON COLUMNS
  DIMENSIONS ga:latitude, ga:longitude ON ROWS TOP 200 BY ga:pageviews DESC
FROM default
WHERE
  TIMEFRAME default

will return data in Data Format 1.

Marker map in iGoogle

To get these results into an iGoogle map, you would do the following:

1. login to ShufflePoint and launch the Query Tool
2. paste the query into the "Query" tab and click "Get results"
3. change to the "Feeds" tab, select "Google Gadgets (JSON)" in the drop-down, and click "Generate"
4. click "Copy" to copy the feed url into your clipboard

Now on iGoogle, add the "Value Map" gadget, put the cursor into the required "Data source url" field, and paste from the clipboard. Give it a title, set the Map to "World" and the Data Display to "Markers" and click "Save". After a few moments, you should see the world map with markers representing pageviews in the top 200 locations.

In Marker mode, the circular marks have both their size and color controlled by the corresponding value - in this case pageviews.

Region map in iGoogle

The region map iGoogle example uses a query which selects the dimension sp:countryCode instead of latitude and longitude. Generate the data feed URL in the Query Tool as before. In the iGoogle settings, specify "Regions" for the Data Display. An example of the resulting display is shown below.

Marker map in web page

I created a sample which runs a query and draws a map using the Javascript Visualization API. This was basically a copy-paste exercise from previous examples show in our blog. View source on the sample to see the code. Note that the "geomap" package is loaded and also note that the dataMode option is set to "markers". When you run this example, you'll observe that the mouseover shows latitude and longitude. This is because the result set returned by the query only has three columns. To get a fourth label column, I modified the query to be:

SELECT
  METRICS ga:pageviews ON COLUMNS
  DIMENSIONS ga:latitude, ga:longitude, ga:region, ga:city ON ROWS 
     TOP 200 BY ga:pageviews DESC
FROM default
WHERE
  TIMEFRAME default

However, I cannot feed this result directly into the gadget. First I need to manipulate the returned data table and concatenate region into the last column of the table. This is accomplished in the second sample. View source to see the Javascript involved, which is a common pattern I used when manipulating datatables:

1. add new column
2. iterate rows and create a derived value to put in new column
3. remove original columns

The live sample can be seen here.

Region map in web page

To the complete the series, I created a region map using the visualization API. Much the same code as in the marker example but as in the iGoogle example, the query now selects sp:regionCode rather than latitude and longitude.

I noticed in reviewing the reference page that the geomap visualization gadget supports user interaction. You can register a region click handler. The handler gets an even which includes a region property so you can take some action based upon what region was clicked. In my sample, I take the action of "zooming in" on the selected region by running a new query specific to that region and refreshing the display with the returned result table. I only implemented US clicks in my sample. This gadget also supports the display of a "zoom out" button. I set showZoomOut to "true" and registered a handler which reruns the original world-level query.

The live sample can be seen here.

Summary

I am glad that a customer recently asked me what we can do with maps. It resulted in my going to have a look at the current Google gadget offerings, and I am pleased that the new stuff is fairly powerful and yet still easy to use. There are some additional map settings I didn't have time to try, such as setting the color scale for the data display. I expect that Google will over time add additional capabilities and settings to the map gadget. On my wish list would be the ability to present pie charts instead of single-value markers.

Live samples

geomap-marker.aspx

geomap-marker-labels.aspx

geomap-region.aspx

References

Visualization: Geomap

http://code.google.com/apis/visualization/documentation/gallery/geomap.html

Tag Clouds are a very common paradigm for navigation on blogs and web sites. The typical tag cloud consists of a block of works, one after another, usually ordered alphabetically and with font size being used to represent a variable such as the number of articles so tagged or the number of searches performed on a particular tag.

I am going to set out in this article to create a Google Gadget which implements a tag cloud from data obtained from Google Analytics.

Using custom variables to tag pages

First, consider how you can "tag" pages with Google Analytics. There two approaches you can use to use the Tracking API to tag pages. One would involve custom variables and the use of the setCustomVar() JavaScript tagging function.

So to tag a page with the tags "analytics" and "reports", you could have for example

_setCustomVar(1, "tag", "analytics")
_setCustomVar(2, "tag", "reports")

Then a query can get the values of the page tags with a query such as:

SELECT
   METRICS ga:pageviews ON COLUMNS
   DIMENSIONS ga:pagePath, ga:customVarValue1,ga:customVarValue2 ON ROWS 
   TOP 50 BY ga:pageviews DESC
FROM [www.shufflepoint.com]
WHERE
   TIMEFRAME yearToDate
   FILTER ga:customVarName1 == "tag" OR ga:customVarName2 == "tag"

The results would have to then be post-processed to merge the two columns of tags into a single tag list sorted by pageviews.

The advantage of tagging pages using custom variables is that you get to choose the domain of tags. However GA only allows five custom variables per page, so you really need to think about both the tags domain and about each pages tags. It sure would be nice to have ten custom variables available. I don't see anything which would prevent one from implementing this approach, but since we don't have such tags now in our GA, it wasn't implemented for this article.

Using keywords instead of tags

The other way to approach building a tag cloud from GA is to use keywords as tags. This is thus closer to a "folksonomy" in that your users are effectively creating the domain of tags. There are two possible sources of keyword tags available in GA - organic search and site search.

If you setup Google Site Search early on, and have steered users towards using it, then that would be the best place to obtain your tag folksonomy. A query such as the one below will get your top search terms. In this example, I've filtered out "search" as a keyword because that word may be present in the search text field as a user hint and I don't want to consider those results. Also I've limited the the results to the top three dozen by pageviews and specified with NOOTHER that I don't want ShufflePoint to calculate an "Other" record.

SELECT
  METRICS ga:pageviews ON COLUMNS
  DIMENSIONS ga:searchKeyword ON ROWS TOP 36 NOOTHER BY ga:pageviews DESC
FROM default
WHERE
  TIMEFRAME yearToDate
  FILTER ga:searchUsed == "Visits With Site Search" AND ga:searchKeyword != "search"

If you haven't setup Site Search, or you find that you don't have enough usage to get a good tag set, you can try looking at organic search as a source for you tag domain. This would be accomplished with a query such as

SELECT
  METRICS ga:pageviews ON COLUMNS
  DIMENSIONS ga:keyword ON ROWS TOP 36 NOOTHER BY ga:pageviews DESC
FROM default
WHERE
  TIMEFRAME yearToDate
  FILTER ga:keyword != "(not set)"

ShufflePoint will return the dataset in Google's Visualization API JSON format. So I have two tasks to tackle. The first is to render the results out as an HTML tag cloud. The second is to add a useful behavior to this tag cloud.

Rendering the cloud

I Googled on tag cloud generators and found there to be nothing complicated - you just have a list of links in a div element and set the font size to be proportional to the frequency. If you want some richer tag cloud visualizations, there is a nice jQuery library at http://plugins.jquery.com/node/3109. For some ideas on how cool a tag could be, check out http://www.wordle.net/. If anybody knows of an interactive (i.e. Flex or AJAX) tagcloud generator like Wordle, please, please let us know!

Handling clicks

How clicks are handled depends on which pattern of query was used to get the tag list. If the Site Search pattern was used, then the tags should be linked to the Site Search page - with the selected tag set as the search parameter. This is the idea approach because users remain on your web site (Google provides a JSON search feed interface).

If you are using the organic search query pattern, then you have two options. You could signup for Site Search now, and create a new page (using Google's JSON feed) to display search results. If you don't want to signup for Site Search, then your tag links will be to Google's search page so users will be leave your site to see the list of pages which contain the tag. But the search expression will include a site qualifier, so all search results links will direct the user back to your own site. Site Search is only $100/year for a typical size site - a small price to pay for the capabilities it offers.

This screenshot shows example of the final cloud. Notice that a timeframe dropdown is present. This allows the visitor to dynamically adjust the timeframe of the query which is retrieving the ranked keywords used to render the cloud.

And finally here is an online demo.

ShufflePoint blog readers know that I love Google Visualization Gadgets and the Visualization API. The standardized HTTP/JSON handshake of the library allows any visualization gadget - including iGoogle gadgets - to consume data which adheres to the visualization API specification. Up to now our examples have used Google-provided gadgets. But for a recent project, I needed something special. Fortunately, custom gadgets are really simple to create because one merely has to implement a simple JavaScript interface to get a custom gadget.

To cut to the chase, here is a link to the sample.

The custom gadget I wanted was something which will be recognizable to anyone using YouTube or other social media sites. Our need was for a gadget which displayed top page visits for the week, month, and year. Most web sites could benefit from such a gadget since it allow you to point out to visitors the "hot" content on the site. And since Google Analytics has this information, it should be relatively easy.

The GAQL query for top pages

The query I will use for this is show below

SELECT
 METRICS ga:visits ON COLUMNS
 DIMENSIONS ga:pagePath, ga:pageTitle ON ROWS TOP 10 NoOther BY ga:visits
FROM default
WHERE
 TIMEFRAME lastMonth

It retrieves the page path and page title for the top 10 pages by visits. The "NoOther" qualifier is present to prevent the addition of an "other" row. This is needed because the default GAQL interpretation will turn

 TOP 10 BY ga:visits

into

 TOP 10 BottomOther BY ga:visits

which adds a bottom row which aggregates all values not in the "top N".

The gadget design

The desired presentation of this gadget is as a small panel which could be added to a narrow left or right callout column of the web site - perhaps below the navigation menu. The query includes the ga:pagePath and ga:pageTitle dimensions to allow the gadget to display a list of page titles where each entry is a link to that page.

The final result is shown in the screenshot below.

Implementing the gadget interface

A gadget is merely a JavaScript class which has two methods. The constructor method takes a single "container" parameter. The container is the HTML element into which the gadget will draw its presentation of the data. The other method has the signature

 draw(data, options)

The data parameter is a DataTable (http://code.google.com/apis/visualization/documentation/reference.html#DataTable) object. The options parameter is an associative array. The user of the gadget can pass in arbitrary (but documented by the gadget author) presentation options.

Our gadget implementation (see TopPagesGoogleVis.js) is pretty straight forward. The draw() method builds an HTML table and then places it in the innerHTML of the container obtained in the constructor. The whole gadget class is less than 50 lines of code (excluding comments).

Using the custom gadget

The code for an HTML page to use this gadget looks pretty much the same as our previous gadget examples. That is because the Google Visualization logic is all the same: a) specify a provider, b) specify and run a query, and c) pass the query results to the gadget.

The gadget containing page has the logic to display a list of timeframes: Last week, Last month, and Last year. It also has an event handler which reruns the query with the selected timeframe. An alternative implementation would be to move this logic into the gadget, but this being my first gadget, I wanted to keep it simple.

Demo: top pages gadget to the sample.

Resources

TopPagesGoogleVis.js - custom gadget