March 30, 2008 | jeffreybarke
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? 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
chtm is the geographical area of the map. This is a required parameter for the map chart type. Valid values include:
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
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:
chf specifies a solid fill. Our
chf value is
bg is a background fill. While normally the first value of
chf can be
a, the map chart type only supports
s specifies a solid fill. The final value is a RRGGBB format hexadecimal number, here a pale blue.
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.1" 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.1" 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
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
The chart data parameter,
chd, has been changed from an underscore to
f9. There are two values here,
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
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
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:
- I removed the
chfparameter. 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.
chcoparameter has received an additional color, instead of
ffffff,0000ff,cccccc,ff0000. The default color is still
ffffff(white), but it's no longer a white to red gradient, but a
cccccc(light grey) to
chldparameter now contains all of the US state codes:
chdparameter has been set to
s:99teAtAAttA9A9O9eeAAAAA9et9eOAOA99e9AAA99e99A9AeA9, which is our data in Google's simple encoding. There are 50 values in our
chdparameter, which correspond to the 50 state codes in our
chldparameter. The color of the states depends on the
chcoparameter: 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).
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).
Red state/blue state data from Wikipedia
Published by: jeffreybarke in The Programming Mechanism