Thematic mapping with the Google Charts API: A brief tutorial

This brief tutorial assumes a basic knowledge of the Google Charts API, but no knowledge of the new map chart type. This tutorial will cover all of the required and optional Charts API parameters for the map chart type and will culminate in displaying a US map of red states and blue states.

Producing the base map

To produce our base map using the Google Charts API requires a URL similar to the following one:

is the chart API's location.

is the chart's size in pixels. This is a required parameter for all charts and the maximum chart size is 440 x 220 pixels. Our map is 350 x 200 pixels.

is the chart type. This is a required parameter for all charts. The map chart type is

.

is the geographical area of the map. This is a required parameter for the map chart type. Valid values include:

• africa
• asia
• europe
• middle_east
• south_america
• usa
• world

contains the chart's data. This is a required parameter for all charts, but we're not ready to display any data on our map yet. To do this, we set the parameter to the underscore character, which "specifies a missing value in simple encoding and gives us the simplest map possible.¹"

Adding color to the map

Adding color to the map is a bit complicated, since color on a thematic map is related to its data. The above map is produced by the following URL:

Most of the parameters are the same as described for our base map, so I'll only cover the new and changed ones below:

specifies a solid fill. Our

value is

, where

is a background fill. While normally the first value of

can be

,

, or

, the map chart type only supports

.

specifies a solid fill. The final value is a RRGGBB format hexadecimal number, here a pale blue.

The

parameter specifies the colors for our map in RRGGBB format hexadecimal numbers. The

for our map is set to

. The first value is the default color "applied to countries or states that are not listed in the

parameter.¹" The second and third colors "specify the extremes of a color gradient that is used to color all countries listed in the

parameter. The color that is applied depends on the country's value in the

parameter.¹" In our example, the default color is set to

(white), the bottom of the gradient is also set to

(white), and the top of the gradient is set to

(red).

The

parameter is a list of codes for each country or state, either ISO 3166-1-alpha-2 codes for countries as defined by ISO3166 or USA state codes. In our example,

is set to

, Wisconsin and New York, the two states I have lived in. Since these are the only two state codes listed, the remainder of the states will be rendered white, since the first

value is

. Depending on their

values, Wisconsin and New York will be rendered using a color gradient that runs from

(white) to

(red) as specified in the second and third

values.

The chart data parameter,

, has been changed from an underscore to

. There are two values here,

and

, corresponding to Wisconsin and New York.

equals 31 in Google's simple encoding and

equals 61, the maximum value possible in simple encoding. Since

is the maximum value, New York will be rendered as

, the top of our gradient specified in

.

(31) is approximately the center of simple encoding and therefore will be rendered as the interpolated center of our gradient, between

(white) and

(red).

The full map: Red states, blue states

Our final map is specifed by the following URL:

This URL is quite similar to the one used in the previous section (there are no new parameters), but with additional data and extra color. Let's examine some of the changes:

1. I removed the

   1

   chf

   parameter. Since there's now so much color on the map, I felt the presence of a light blue background color for water elements was distracting.

2. The

   1

   chco

   parameter has received an additional color, instead of

   1	ffffff,ffffff,ff0000

   it's now

   1	ffffff,0000ff,cccccc,ff0000

   . The default color is still

   1

   ffffff

   (white), but it's no longer a white to red gradient, but a

   1

   0000ff

   (blue) to

   1

   cccccc

   (light grey) to

   1

   ff0000

   (red) gradient.

3. The

   1

   chld

   parameter now contains all of the US state codes:

   1	ALAKAZARCACOCTDEFLGAHIIDILINIAKSKYLAMEMDMAMIMNMSMOMTNENVNHNJNMNYNCNDOHOKORPARISCSDTNTXUTVTVAWAWVWIWY

4. The

   1

   chd

   parameter has been set to

   1	s:99teAtAAttA9A9O9eeAAAAA9et9eOAOA99e9AAA99e99A9AeA9

   , which is our data in Google's simple encoding. There are 50 values in our

   1

   chd

   parameter, which correspond to the 50 state codes in our

   1

   chld

   parameter. The color of the states depends on the

   1

   chco

   parameter: in simple encoding, A = 0, which will render on our map as blue, O = 15 (which will render pale blue) e = 30 (light gray), t = 45 (pale red), and 9 = 61 (red).

Some observations

Bjørn Sandvik² writes:

So far, I find the mapping feature of Google Chart API more suitable for "country highlighting" than for thematic mapping. The maximum size for maps (440 by 220 pixels) is too restrictive, as a world map needs more detail. I also miss a map legend, so the map reader can spot which colours represent high/low values.

I agree with Bjørn that the lack of an API-generated legend is problematic, though one could be constructed via HTML adjacent to the chart. I also feel that maximum map size is adequate for a US map, though the quality leaves something to be desired (compare to the Wikipedia red state/blue state map).

Sources

1. Developer's Guide—Google Charts API
2. Thematic Mapping Blog

Red state/blue state data from Wikipedia