Overview

You can create a map with various countries or states highlighted in custom
colors. You can let the map zoom to the proper level to display your selected countries
properly, or you can zoom in or out to a custom level using latitude and longitude
values.

Supported Parameters

Map charts support the following parameters:

Parameter

Required or Optional

Description

cht=map<opt_zoom_and_center>

Required

Specifies a map chart.

opt_zoom_and_center - An optional string that enables you to zoom or center the chart on a specific region. See details.

If used, the data value will indicate the color of the corresponding
country, along the color gradient specified by chco.

chld=
<country_or_region_codes>|...|

Required

A pipe-separated list of countries or states that will be highlighted
in colors specified by chco. The map will automatically
zoom to include all the countries specified, unless you do custom zooming
or centering. Codes
must be uppercase. These codes are ISO
3166-1-alpha-2 codes: two uppercase characters, optionally
followed by a dash and a second identifier for regions or cities. Examples:
GB (Great Britain), GB-LND (London), US-NJ (state of New Jersey in the
United States)

Chart colors. The format of this string depends on whether you use
chd. In
both syntaxes, <unselected_land_color> is
the color of any regions not specified in chld. Note that
the dividers are different for the
different syntaxes (commas
in one, pipes in the other). If not used, regions will be outlined but
not colored.

chd used - The second
and later colors describe a color range.
You must have one chd value for each country in chld,
and the corresponding country
will be colored along a range from <first_region_color> (minimum data range value) to <last_region_color> (maximum
data range value). See examples in the table below.

chd not used - The
second and later colors are applied to the corresponding regions
in chld,
in the order listed. If there are more
countries than colors, the last color will be applied to all excess
countries in the list.

chld=FR-D|FR-B|FR - Three regions are specified: Bourgogne
(in the east), Aquitaine (in the southwest), and France.

chco=676767|FF4444|44FF44|4444FF - No chd parameter
is specified in this map, so each color
value after the first is used to specify the corresponding country.
Red for Bourgogne, green for Aquitaine, blue for France. You can
see that later colors do not mask earlier colors.

chld=FR-D|FR-B|FR
chco=676767|FF4444|44FF44|4444FF

This map demonstrates using color gradients.

chd=t:0,50,100 - The chd parameter indicates a color
gradient. Here, text encoding is specified, which has a range from
0—100.

chco=CCCCCC,FF0000,000000 - Background color is light
gray (CCCCCC), and the color range is from red
(FF0000)
to black (000000).
The middle country shown is an intermediate color on that gradient.

chd=t:0,50,100
chco=CCCCCC,FF0000,000000

Note that the map can be cropped inside the
specified chart size. This is because we will not distort a map to fit
inside a specified chart size, but we limit the map to the regions that
you specify in chld.
Therefore, to avoid cropped regions inside the chart boundaries, you
might have to adjust the map size manually.

cht=map
chs=300x300
chld=GB

England is naturally long and thin, so specifying
a square map includes a cropped area on the right side:

cht=map
chs=180x300
chld=GB

Adjust the chart width to crop off the excess. Note
how there's still some cropping on the bottom that should be
fixed by reducing the map height.

cht=map
chs=180x300
chld=GB

France is much more regularly shaped, so it fits more naturally
in a square map.

Zooming and Centering

By default, the chart will be zoomed and centered to center
your selected regions, and make them fit into the rendered area as closely as possible,
within the defined map size. However, you can customize the centering and zooming
level of the chart in two different ways:

Where <bottom_border_lat> and <top_border_lat>
specify the latitude of
the bottom and top borders, and <left_border_long> and <right_border_long>
specify the longitude of the left and right borders.

Note: Because of Mercator projection distortion (basically, projecting a curved
map onto a flat image), focusing on a tall, narrow strip can cause some unexpected
size differences in your map.

Examples:

The following examples show London (highlighted in blue) which is 0.1° longitude,
51.5° latitude. Note how there is map cropping because
the map is trying to display only Great Britain (as specified) and fill the designated
chart without distortion.

Centered

Latitudes shifted +10*

Zoomed by reducing all values

cht=map:fixed=40,-10,60,10

cht=map:fixed=50,-10,70,10

cht=map:fixed=48,-3,54,3

Note how the size of the middle image is a bit smaller than the first image, even
though we've moved the same number of degrees up. This is because we're projecting
a 3-D sphere onto a 2-D image. You would have to increase the width of the second
chart to make it the same size as the first chart.

Standard Features

Chart Title chtt, chts [All
charts]

You can specify the title text, color, and font size for your chart.

Syntax

chtt=<chart_title>
chts=<color>,<font_size>,<opt_alignment>

chtt - Specifies the chart title.

<chart_title>

Title to show for the chart. You cannot specify where this appears, but you
can optionally specify the font size and color. Use a + sign to indicate spaces,
and a pipe character ( | ) to indicate line breaks.

Chart Margins chma [All
charts]

You can specify the size of the chart's margins, in pixels. Margins are calculated
inward from the specified chart size (chs); increasing the margin
size does not increase the total chart size, but rather shrinks the chart area,
if necessary.

The margins are by default whatever is left over after the chart size is calculated.
This default value varies by chart type. The margins that you specify are a minimum value;
if the chart area leaves room for margins, the margin size will be whatever is
left over; you cannot squeeze the margins smaller than what is required
for any legends and labels. Here's a diagram showing the basic parts of a
chart:

The chart margins include the axis labels and the legend
area. The legend
area resizes automatically to fit the text exactly, unless you specify a larger
width using chma, in which case it will expand the margin size wider, squeezing
the chart area smaller. You cannot crop a legend by specifying a size that
is too small, but you can make it take up more space than it needs.

Tip: In a bar chart, if the bars have a fixed size (the default), the chart
area width cannot be reduced. You must specify a smaller or resizeable bar
size using chbh.

Minimum margin size around the chart area, in pixels. Increase this value to
include some padding to prevent axis labels from bumping against the borders
of the chart.

<opt_legend_width>,
<opt_legend_height>

[Optional] Width of the margin around the legend, in pixels.
Use this to avoid having the legend bump up against the chart area or the edges
of the image.

Examples

Description

Example

In this example, the chart has a minimum margin of 30 pixels
on each side. Because the chart legend is more than 30 pixels wide, the
margin on the right side is set to the width of the chart legend, and is
different from the other margins.

Axis labels are outside the plot area, and are therefore drawn within
the margin space.

chma=30,30,30,30

To add a margin around the legend, set a value for the <opt_legend_width> and <opt_legend_height> parameters.

In this example, the legend is approximately 60 pixels wide. If you set
the the <opt_legend_width> to 80 pixels, the margin
extends to 20 pixels outside the legend.

Background Fills chf [All
charts]

You can specify fill colors and styles for the chart data area and/or the whole
chart background. Fill types include solid fills, striped fills, and gradients.
You can specify different fills for different areas (for example, the whole chart
area, or just the data area). The chart area fill
overwrites the background fill. All fills are specified using the chf parameter,
and you can mix different fill types (solids, stripes, gradients) in the same chart
by separating values with pipe character ( | ). Chart area fills overwrite chart
background fills.

Solid Fills chf [All
Charts]

You can specify a solid fill for the background and/or chart area, or assign a
transparency value to the whole chart. You can specify multiple fills using the
pipe character (|). (Maps: background only).

Syntax

chf=<fill_type>,s,<color>|...

<fill_type>

The part of the chart being filled. Specify one of the following values:

bg - Background fill

c - Chart area fill. Not supported for map charts.

a - Make the whole chart (including backgrounds) transparent.
The first six digits of <color> are ignored,
and only the last two (the transparency value) are applied to the whole chart
and all fills.

b<index> - Bar solid fills (bar charts only).
Replace <index> with the series index of the bars to fill
with a solid color. The effect is similar to specifying
chco in a bar chart. See Bar
Chart Series Colors for an example.

s

Indicates a solid or transparency fill.

<color>

The fill color, in RRGGBB hexadecimal format. For transparencies, the
first six digits are ignored, but must be included anyway.

Examples

Description

Example

This example fills the chart background with pale gray
(EFEFEF).

chf=bg,s,EFEFEF

This example fills the chart background with pale gray
(EFEFEF) and fills the chart area in black (000000).

chf=c,s,000000|
bg,s,EFEFEF

This example applies a 50% transparency to the whole chart
(80 in hexadecimal is 128, or about 50% transparency). Notice the table cell
background showing through the chart.

Chart Legend Text and Style chdl, chdlp, chdls [All
charts]

The legend is a side section of the chart that gives
a small text description of each series. You can specify the text associated
with each series in this legend, and specify where on the chart it should appear.

A note on string
values: Only
URL-safe characters are permitted in label strings. To be safe, you should URL-encode
any strings containing characters not in the character set 0-9a-zA-Z.
You can find a URL encoder in the Google Visualization
Documentation.

The text for the legend entries. Each label applies to the corresponding series
in the chd array. Use a + mark for a space. If you do not specify
this parameter, the chart will not get a legend. There is no way to specify a
line break in a label. The legend will typically
expand to hold your legend text, and the chart area will shrink to accommodate
the legend.

chdlp - [Optional] The position of
the legend, and order of the legend entries. You can specify <position>
and/or <label_order>. If you specify both, separate them with a bar
character. You can add an 's' to any value if you want empty legend entries in
chdl to be skipped in the legend. Examples: chdlp=bv, chdlp=r, chdlp=bv|r, chdlp=bvs|r

<opt_position>

[Optional] Specifies the position of the legend on the chart. To specify additional
padding between the legend and the chart area or the image border, use the chma parameter.
Choose one of the following values:

b - Legend at the bottom of the chart, legend entries in a
horizontal row.

bv - Legend at the bottom of the chart, legend entries in
a vertical column.

t - Legend at the top of the chart, legend entries in a horizontal
row.

tv - Legend at the top of the chart, legend entries in a vertical
column.

r - [Default] Legend to the right of the chart, legend
entries in a vertical column.

l - Legend to the left of the chart, legend entries in a vertical
column.

<opt_label_order>

[Optional]
The order in which the labels are shown in the legend.
Choose one of the following value:

l - [Default for vertical legends]
Display labels in the order given to chdl.

r - Display labels in the reverse order as given to chdl.
This is useful in stacked bar charts to show the legend
in the same order as the bars appear.

a - [Default for horizontal legends] Automatic ordering:
roughly means sorting by length, shortest first, as measured in 10 pixel
blocks. When two elements are the same length (divided into 10 pixel blocks),
the one listed first will appear first.

0,1,2... - Custom label order. This is a list of zero-based
label indexes from chdl, separated by commas.

chdls - [Optional] Specifies the color and font size of the legend text.

Shape Markers chm [Bar, Line,
Radar, Scatter]

You can specify graphical markers for
all or individual data points on a chart. If two or more markers occupy the same
point, the markers are drawn in the order in which they appear in the chm parameter.
You can also create text markers on data points, which is covered in Data
Point Markers.

You can combine shape markers with
any other chm parameters using a pipe character ( | )
to separate the chm parameters.

Syntax

Specify one set of the following parameters
for each series that should be marked. To mark multiple series, create additional
parameter sets, delimited by a pipe character. You do not need to mark up
all series. If you do not assign markers to a data series, it will not get any
markers.

Shape markers behave slightly differently in scatter
charts. See that documentation
for more information.

[Optional] If you precede the marker type with the optional @ character,
then <opt_which_points>
should use the x:y format.

<marker_type>

The type of marker to use. Specify one of the following
types:

a - Arrow

c - Cross

C - Rectangle. If a rectangle marker, you must have at least
two data series, where series 0 specifies the bottom edge and series 1 specifies
the top edge. <size>
specifies the width of the rectangle, in pixels.

d - Diamond

E - Error-bar marker ( )
This marker requires two data series to create, one value for the bottom,
and the corresponding point in the second series for the top. It also exposes
an extended <size> syntax: line_thickness[:top_and_bottom_width] where
top_and_bottom_width is optional. See the examples below.

h - Horizontal line across the chart at a specified height.
(The only valid format for <opt_which_points> parameter
is n.d.)

H - Horizontal line through the specified data marker. This supports an extended
<size> syntax that lets you specify an exact line length: line_thickness[:length]
where :length is optional, and defaults to the full chart area width.

o - Circle

s - Square

v - Vertical line from the x-axis to the data point

V - Vertical line of adjustable length. This supports an extended
<size> value syntax that lets you specify an exact line length: line_thickness[:length]
where :length is optional, and defaults to the full chart area height.
The marker is centered on the data point.

The zero-based index of the data series on which to draw the markers. Ignored
for h markers and markers that specify location by x/y position
(start with the @ character). You can use hidden data series as a source for markers; see Compound Charts for more information. Grouped vertical bar charts support a special extended syntax to align markers with specific bars.

<opt_which_points>

[Optional] Which point(s) to draw markers on. Default is
all markers. Use one of the following values:

n.d - Where to draw the marker. The meaning depends
on the marker type:

All types except h - Which data point to draw the marker
on, where n.d is the zero-based index in the series. If you
specify a non-integer value, then the fraction indicates a calculated
intermediate point. For example, 3.5 means halfway between point 3
and point 4.

h - A number from 0.0
to 1.0, where 0.0 is the bottom of the chart, and 1.0 is the top of the
chart.

-1 - Draw a marker on all data points. You can also leave
this parameter empty to draw on all data points.

-n - Draw a marker on every n-th data point. Floating
point value; if n is less than 1 the chart will calculate additional intermediary
points for you. For example, -0.5 will put twice as many markers as data
points.

start:end:n - Draw a marker on
every n-th
data point in a range, from start to end index values,
inclusive. All parameters are optional (may be absent), so 3::1 would be
from the fourth element to the last, step 1, and omitting this parameter
entirely would default to first:last:1. All values can
be floating point numbers. start and end can be negative,
to count backward from the last value. If both start and end are negative,
be sure that they are listed in increasing value (for example, -6:-1:1).
If the n step
value is less than 1, it will calculate additional data points by interpolating
the data values given. Default values are first:last:1

x:y - Draw a marker at a specific x/y point on the chart.
This point does not have to be on a line. Add the @ character before the
marker type to use this option. Specify the coordinates as floating point
values, where 0:0 is the bottom left corner of the chart and 1:1 is
the top right corner of the chart. For example, to add a red, 15-pixel diamond
to the center of a chart, use @d,FF0000,0,0.5:0.5,15.

<size>

The size of the marker, in pixels. Most take a single number value for this parameter;
the V, H, and S markers support the syntax <size>[:width]
where the optional second part specifies the line or marker length.

<opt_z_order>

[Optional] The layer on which to draw the marker, compared to
other markers and all other chart elements. This is a floating point number from
-1.0 to 1.0, inclusive, where -1.0 is the bottom and 1.0 is the top. Chart
elements (lines and bars) are just lower than zero. If two markers have the same
value, they are drawn in the order given by the URL. Default value is 0.0 (just
above the chart elements).

<opt_offset>

[Optional] Let you specify horizontal and vertical offsets from the
specified location. Here is the syntax, which uses a : delimiter: reserved:<horizontal_offset>:<vertical_offset>.
If specified, you can include an empty ,, value in the chm parameter
string for <opt_z_order>. Examples: o,FF9900,0,4,12,,:10 o,FF9900,0,4,12.0,,:-10:20 o,FF9900,0,4,12,1,::20

reserved - Leave blank.

<horizontal_offset> - A positive or negative
number specifying the horizontal offset, in pixels. Optional; leave blank
if not used.

<vertical_offset> - A positive or negative
number specifying the vertical offset, in pixels. Optional; leave blank
if not used.

Here's an example using diamonds for one data series, and
circles for the other data series.

If two or more markers occupy the same point, the markers are drawn in
the order in which they appear in the chm parameter. Here,
the circle is the first marker specified with chm, so it is
drawn first. The diamond is specified and drawn second, which results in
it being drawn on top of the circle.

chm=
o,FF9900,0,-1,15.0|
d,FF0000,1,-1,10.0

Here's a line chart with a marker on every second data
point (-2 means every other point).

chd=t:
0,20,20,50,40,70,70,90,85,45,40,50
chm=
o,0066FF,0,-2,6

Here's a line chart with twice as many markers as data points
(-0.5 means every half point).

chd=t:
0,20,20,50,40,70,70,90,85,45,40,50
chm=
o,0066FF,0,-.5,6

This example shows how to use h and v markers
to create grid lines with custom colors and thickness. The z-order value
(the last value) is set to -1 so that the grid lines are drawn
beneath the data line.

chm=
h,76A4FB,0,0:1:.2,2,-1|
V,76A4FB,0,::2,0.5,-1

This chart adds vertical fill lines to a line chart:

v - Vertical lines to the chart

FF0000 - Red lines

0 - Series index

: :.5 - Range specifier: from start to end, every 0.5 points.

2 - Thickness 2 pixels.

chm=
v,FF0000,0,::.5,2

This example adds an arrow and text marker to the chart using
exact coordinates. The first D marker is the trace line under the bars. The
second marker is the arrow, and the third marker is the arrow text.

Text and
Data Value Markers chm [Bar, Line,
Radar, Scatter]

You can label specific points
on your chart with custom text, or with formatted versions of the data at that
point.

You can combine any chm markers
using a pipe character ( | ) to separate the chm parameter
sets.

A note on string
values: Only
URL-safe characters are permitted in label strings. To be safe, you should URL-encode
any strings containing characters not in the character set 0-9a-zA-Z.
You can find a URL encoder in the Google Visualization
Documentation.

Syntax

Specify one set of the following
parameters for each series that should be marked. To mark multiple series, create
additional parameter sets, delimited by a pipe character. You do not need
to mark up all series. If you do not assign markers to a data series, it will
not get any markers.

f<text> - A flag containing text. Specify the
character 'f', followed by custom URL-encoded text. To
escape commas in text markers, precede the comma by a \ mark. Example: fHello\,+World!

t<text> - A simple text marker. Specify the
character 't' followed by custom URL-encoded text. To
escape commas in text markers, precede the comma by a \ mark. Example: tHello\,+World!

A<text> - An annotation marker. This is similar
to a flag marker, but markers will coordinate their position so that they
do not overlap. The only valid format for <opt_which_points> is
n.d, to signify the index of a point in the series.

N<formatting_string> - The value of the data
at this point, with optional formatting. If you do not use the chds parameter
(custom scaling) it gives the exact encoded value; if you do use that parameter with
any format
type the value will be scaled to the range that you specify.
See an example of chds with
numeric markers below. With this marker type in a stacked
bar chart, if you
specify -1 for <series_index> you will get a marker that shows the sum of
all values in this stacked bar. The formatting string syntax is as follows: <preceding_text>*<number_type><decimal_places>zs<x
or y>*<following_text>.
All of these elements are optional. Here is the meaning of each element:

<preceding_text> - Text to precede each
value.

*...* - An optional block wrapped in literal asterisks,
in which you can specify formatting details for numbers. The following
values are supported, and are all optional:

<number_type> - The number format,
for numeric values. Choose one of the following:

f - [Default] Floating point format.
Consider specifying precision as well with the <decimal_places>
value.

c<CUR> - Format the number in the
currency specified, with the appropriate currency marker.
Replace <CUR> with
a three-letter currency code. Example: cEUR for
Euros. You can find a list of codes on the ISO
web site, although
not all symbols are supported.

<decimal_places> - An integer specifying
how many decimal places to show. The value is rounded (not truncated)
to this length. Default is 2.

z - Display trailing zeros. Default is
no.

s - Display group separators. Default is no.

x or y -Display the data from the x-
or y-coordinate, as specified. The meaning of x data varies by chart
type: experiment with your chart to determine what it means. Default
is 'y'.

The zero-based index of the data series on which to draw the markers. If this
is a stacked bar chart and the marker type is N (data point values), you can
specify -1 to create a summed value marker for each stack of bars. See below
for an example.

<opt_which_points>

[Optional] Which point(s) to draw markers on. Default is all markers. Use
one of the following values:

n.d - Which data point to draw the marker on, where
n.d is the zero-based index in the series. If you specify a non-integer
value, then the fraction indicates a calculated intermediate point. For example,
3.5 means halfway between point 3 and point 4.

-1 - Draw a marker on all data points. You can also leave
this parameter empty to draw on all data points.

-n - Draw a marker on every n-th data point.

start:end:n - Draw a marker on
every n-th data point in a range, from start to end index
values, inclusive. All parameters are optional (may be absent), so 3::1 would
be from the fourth element to the last, step 1, and omitting this parameter
entirely would default to first:last:1. All values can
be floating point numbers. start and end can be negative,
to count backward from the last value. If both start and end are
negative, be sure that they are listed in increasing value (for example,
-6:-1:1). If the n step value is less than 1, it will calculate
additional data points by interpolating the data values given. Default
values are first:last:1

x:y - [Not supported for N-type markers]
Draw a marker at a specific x/y point on the chart. This point does not have
to be on a line. Add the at character (@)
before the marker type to use this option. Specify the coordinates as floating
point values, where 0:0 is the bottom left corner of the chart, 0.5:0.5 is
the center of the chart, and 1:1 is the top right corner of
the chart. For example, to add a red, 15-pixel diamond to the center of a
chart, use @d,FF0000,0,0.5:0.5,15.

<size>

The size of the marker in pixels. If this is a scatter chart with a third
data series (used to specify point sizes), this value will be scaled by the data
range. So if the data range is 0—100 and <size> is 30, a data value of
100 would be 30 pixels wide, a data value of 50 would be 15 pixels wide, and
so on.

<opt_z_order>

[Optional] The layer on which to draw the marker, compared to
other markers and all other chart elements. This is a floating point number from
-1.0 to 1.0, inclusive, where -1.0 is the bottom and 1.0 is the top. Chart elements
(lines and bars) are just lower than zero. If two markers have the same value,
they are drawn in the order given by the URL. Default value is 0.0 (just above
the chart elements).

<opt_placement>

[Optional] Additional placement details describing where to put this
marker, in relation to the data point. You can specify horizontal and/or vertical
relative positioning, as well as offsets. Placement syntax is a string with :
delimiters as shown here. All elements are optional: <horizontal_and_vertical_justification>:<horizontal_offset>:<vertical_offset>.
If specified, you can include an empty ,, value in the chm parameter
string for <opt_z_order>. Examples:
N,000000,0,1,10,,b and N,000000,0,1,10,,lv and N,000000,0,1,10,,r::10.

horizontal_and_vertical_justification

The anchor point of the marker. This behaves opposite to justification,
so a left anchor actually puts the marker to the right of the data
point. You can choose a horizontal
and/or vertical justifier from the following list:

Bar-relative placement [Bar charts only]:
's', 'c', 'e' - Base, center, or top of a bar. For stacked charts,
this is relative to the section of the bar for each series, not for
the whole bar. If the series index given is -1 (stack total) it is
in relation to the whole bar. This can be combined with vertical placement
values: for example, 'be' or 'vs'.
Default value is 'e'.

The first chart (N*p0*) specifies a data value marker, with
values shown as a percentage, rounded to zero decimal
places, in black, on all values, in 11-point text. Note that the data values
are all between 0.0 and 1.0, which, in percentage format, are moved up
two decimal places.

The second chart (N*cEUR1*) shows the same values formatted
as Euro values, one decimal place, in black, on all values, in 11-point
text.

You can use the chds parameter to scale the numeric
value displayed. You can use chds for all data formats, including
simple and extended encoding. This will not affect the bar size or the axis
labels, but only the data marker value.

This example shows a chart with simple-encoded values
of 46, 39, 29, 30, 43, 41. Simple encoding range is 0—61
. The chds parameter defines
a custom marker scale of 0—1,
so marker values are scaled to this range, but the bar heights are not affected
(if this were text
format data,
the bars would be scaled as well).

chd=s:underp
chm=N,000000,0,-1,11
chds=0,1

Here's an example of a chart with a text label at the minimum point
and a flag label at the maximum point.

chm=
tMin,0000FF,0,1,10|
fMax,FF0000,0,3,15

This example shows a stacked chart with values for individual series, plus
the series total. To show the stacked series values, we must use the 'c'
positioning option; if we did not,
the top bar value would overlap the sum value at the top of each bar.

Some more demonstrations of how vertical and horizontal placement work.
This example demonstrates various combinations of anchor values for bar charts
(which use s, c,and e for vertical placement). Note
how a right anchor moves a marker left, and a top anchor moves a marker down,
and vice-versa. The red dots show the base, center, and top of each bar.
The number is the data value, fixed using different anchor values for each
bar.