Thematic mapping with the Google Charts API: A brief tutorial

March 30th, 2008  |  web development, web mapping

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

United States of America

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

1
http://chart.apis.google.com/chart?chs=350x200&cht=t&chtm=usa&chd=s:_

1
http://chart.apis.google.com/chart?

is the chart API's location.

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

1
cht

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

1
t

.

1
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

1
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.1"

Adding color to the map

Wisconsin and New York

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:

1
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:

1
chf

specifies a solid fill. Our

1
chf

value is

1
bg,s,eaf7fe

, where

1
bg

is a background fill. While normally the first value of

1
chf

can be

1
bg

,

1
c

, or

1
a

, the map chart type only supports

1
bg

.

1
s

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

The

1
chco

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

1
chco

for our map is set to

1
ffffff,ffffff,ff0000

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

1
chld

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

1
chld

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

1
chd

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

1
ffffff

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

1
ffffff

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

1
ff0000

(red).

The

1
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,

1
chld

is set to

1
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

1
chco

value is

1
ffffff

. Depending on their

1
chd

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

1
ffffff

(white) to

1
ff0000

(red) as specified in the second and third

1
chco

values.

The chart data parameter,

1
chd

, has been changed from an underscore to

1
f9

. There are two values here,

1
f

and

1
9

, corresponding to Wisconsin and New York.

1
f

equals 31 in Google's simple encoding and

1
9

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

1
9

is the maximum value, New York will be rendered as

1
ff0000

, the top of our gradient specified in

1
chld

.

1
f

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

1
ffffff

(white) and

1
ff0000

(red).

The full map: Red states, blue states

Red States and Blue States, USA

Our final map is specifed by the following URL:

1
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
    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 Sandvik2 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

  • http://maps.webfoot.com Kaitlin Duck Sherwood

    Nice tutorial!

    FYI, I have a service that creates KML thematic maps (that can then be overlaid on Google Maps) at
    http://maps.webfoot.com/mapeteria

    It’s not better than using the Charts API, it’s different.

    Also, if you want to make a map of slightly different areas (e.g. counties of Maine, as someone I corresponded with this morning did), I’ve open-sourced the code, so you could extend it for arbitrary polygons. (You do have to have/create a KML file with the polygons you are interested in coloring, however.)

  • Pingback: 50 Cool Things You Can Do with Google Charts API | College@Home

  • http://www.definitely-inclusive.org cabotine

    Do you know where to find imagemaps for the maps of the google chart api (the continents)