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:
http://chart.apis.google.com/chart?chs=350x200&cht=t&chtm=usa&chd=s:_

http://chart.apis.google.com/chart? is the chart API's location.

chs 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.

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

chtm 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

chd 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: http://chart.apis.google.com/chart?chs=350x200&cht=t&chtm=usa&chco=ffffff,ffffff,ff0000&chld=WINY&chd=s:f9&chf=bg,s,eaf7fe

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

chf specifies a solid fill. Our chf value is bg,s,eaf7fe, where bg is a background fill. While normally the first value of chf can be bg, c, or a, the map chart type only supports bg. s specifies a solid fill. The final value is a RRGGBB format hexadecimal number, here a pale blue.

The chco parameter specifies the colors for our map in RRGGBB format hexadecimal numbers. The chco for our map is set to ffffff,ffffff,ff0000. The first value is the default color "applied to countries or states that are not listed in the chld parameter.¹" The second and third colors "specify the extremes of a color gradient that is used to color all countries listed in the chld parameter. The color that is applied depends on the country's value in the chd parameter.¹" In our example, the default color is set to ffffff (white), the bottom of the gradient is also set to ffffff (white), and the top of the gradient is set to ff0000 (red).

The chld 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, chld is set to WINY, 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 chco value is ffffff. Depending on their chd values, Wisconsin and New York will be rendered using a color gradient that runs from ffffff (white) to ff0000 (red) as specified in the second and third chco values.

The chart data parameter, chd, has been changed from an underscore to f9. There are two values here, f and 9, corresponding to Wisconsin and New York. f equals 31 in Google's simple encoding and 9 equals 61, the maximum value possible in simple encoding. Since 9 is the maximum value, New York will be rendered as ff0000, the top of our gradient specified in chld. f (31) is approximately the center of simple encoding and therefore will be rendered as the interpolated center of our gradient, between ffffff (white) and ff0000 (red).

The full map: Red states, blue states

Our final map is specifed by the following URL: http://chart.apis.google.com/chart?chs=350x200&cht=t&chtm=usa&chco=ffffff,0000ff,cccccc,ff0000&chld=ALAKAZARCACOCTDEFLGAHIIDILINIAKSKYLAMEMDMAMIMNMSMOMTNENVNHNJNMNYNCNDOHOKORPARISCSDTNTXUTVTVAWAWVWIWY&chd=s:99teAtAAttA9A9O9eeAAAAA9et9eOAOA99e9AAA99e99A9AeA9

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 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 chco parameter has received an additional color, instead of ffffff,ffffff,ff0000 it's now ffffff,0000ff,cccccc,ff0000. The default color is still ffffff (white), but it's no longer a white to red gradient, but a 0000ff (blue) to cccccc (light grey) to ff0000 (red) gradient.
3. The chld parameter now contains all of the US state codes: ALAKAZARCACOCTDEFLGAHIIDILINIAKSKYLAMEMDMAMIMNMSMOMTNENVNHNJNMNYNCNDOHOKORPARISCSDTNTXUTVTVAWAWVWIWY
4. The chd parameter has been set to s:99teAtAAttA9A9O9eeAAAAA9et9eOAOA99e9AAA99e99A9AeA9, which is our data in Google's simple encoding. There are 50 values in our chd parameter, which correspond to the 50 state codes in our chld parameter. The color of the states depends on the 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