Visualization: Geochart

Overview

A geochart is a map of a country, a continent, or a region
with areas identified in one of three ways:

The region mode colors whole regions, such as countries, provinces, or states.

The markers mode uses circles to designate regions that are scaled according to a value that you specify.

The text mode labels the regions with identifiers (e.g., "Russia" or "Asia").

A geochart is rendered within the browser using
SVG or
VML.
Note that the geochart is not scrollable or draggable, and it's a
line drawing rather than a terrain map; if you want any of that,
consider a
map
visualization instead.

Region Geocharts

The regions style fills entire regions (typically
countries) with colors corresponding to the values that you
assign.

[This section requires a browser that supports JavaScript and iframes.]

Marker Geocharts

The markers style renders circles at specified
locations on the geochart, with the color and size that you
specify. Try hovering over the cluttered markers around Rome,
and a magnifying glass will open to show the markers in more
detail. (The magnifying glass is not supported in Internet
Explorer version 8 or earlier.)

[This section requires a browser that supports JavaScript and iframes.]

Displaying Proportional Markers

Normally, marker geocharts display the smallest marker value as a
minimal point. If you instead want to display proportional marker
values (say, because they're percentages), use
the sizeAxis option to set minValue
and maxValue explicitly.

For instance, here's a map of western Europe with populations and
areas for three countries: France, Germany, and Poland. The
populations are all absolute numbers (e.g., 65 million for France) but
the areas are all percentages of the whole: the France marker is
colored violet because it's population is middling, but is sized 50
(out of a possible 100) because it contains 50% of the combined area.

[This section requires a browser that supports JavaScript and iframes.]

In this code, we use sizeAxis to specify marker sizes
in the range from 0 to 100. We also use a colorAxis with
RGB values to show the populations as a range of colors from orange to
blue, a spectrum that will work well for users with color vision
deficiencies. Finally, we specify western Europe with
a region of 155, per the "Content Hierarchy and Codes"
section later in this document.

Coloring your chart

colorAxis: the spectrum of colors to use for the regions in the datatable.

backgroundColor: the background color for the chart.

datalessRegionColor: the color to assign to regions with no associated data.

The colorAxis option is the important one: it
specifies the range of colors for your data values. In
the colorAxis array, the first element is the color given
to the smallest value in your dataset, and the last element is the
color given to the largest value in yoru dataset. If you specify more
than two colors, interpolation will occur between them.

In the following chart, we'll use all three
options. The colorAxis is used to display Africa with the
colors of the pan-African flag, using the latitudes of the countries:
from red in the north, through black, to green in the
south. The backgroundColor option is used to color the
background a light blue, and datalessRegionColor to color
the non-African countries a light pink.

[This section requires a browser that supports JavaScript and iframes.]

Loading

The geochart visualization class name is google.visualization.GeoChart.

var visualization = new google.visualization.GeoChart(container);

Data format

The format of the DataTable varies depending on which display mode that you use: regions, markers, or text.

Regions mode format

The location is entered in one column,
plus one optional column as described here:

Region location [String, Required] - A region to highlight.
All of following formats are accepted. You can use different formats in different rows:

A country name as a string (for example, "England"), or an uppercase ISO-3166-1 alpha-2 code or its English text equivalent (for example, "GB" or "United Kingdom").

An uppercase ISO-3166-2 region code name or its English text equivalent (for example, "US-NJ" or "New Jersey").

A metropolitan area code. These are three-digit metro codes used to designate various regions; US codes only supported. Note that these are not the same as telephone area codes.

Any value supported by the region property.

Region color [Number, Optional] - An optional numeric column used to assign a color to this region, based on the scale specified in the colorAxis.colors property. If this column is not present, all regions will be the same color. If the column is present, null values are not allowed. Values are scaled relative to the sizeAxis.minValue/sizeAxis.maxValue values, or to the values specified in the colorAxis.values property, if provided.

Markers mode format

The number of columns varies depending on the marker format used, as well as other optional columns.

Marker location [Required]
The first column is a specific string address (for example, "1600 Pennsylvania Ave").OR
The first two columns are numeric, where the first column is the latitude, and the second column is the longitude.

Marker color [Number, Optional] The next column is an optional numeric column used to assign a color to this marker, based on the scale specified in the colorAxis.colors property. If this column is not present, all markers will be the same color. If the column is present, null values are not allowed. Values are scaled relative to each other, or absolutely to values specified in the colorAxis.values property.

Marker size [Number, Optional] An optional numeric column used to assign the marker size, relative to the other marker sizes. If this column is not present, the value from the previous column will be used (or default size, if no color column is provided as well). If the column is present, null values are not allowed.

Text mode format

Text size [Number, Optional] The second column is an optional numeric column used to assign the size of the label. If this column is not present, all labels will be the same size.

Configuration options

Name

Type

Default

Description

backgroundColor

string or object

white

The background color for the main area of the chart.
Can be either a simple HTML color string, for example: 'red' or '#00cc00', or an object with the following properties.

backgroundColor.fill

string

white

The chart fill color, as an HTML color string.

backgroundColor.stroke

string

'#666'

The color of the chart border, as an HTML color string.

backgroundColor.strokeWidth

number

0

The border width, in pixels.

colorAxis

Object

null

An object that specifies a mapping between color column values and colors
or a gradient scale. To specify properties of this object, you can use
object literal notation, as shown here:

{minValue: 0, colors: ['#FF0000', '#00FF00']}

colorAxis.minValue

number

Minimum value of color column in chart data.

If present, specifies a minimum value for chart color data. Color data values of this value and lower will be rendered as the first color in the colorAxis.colors range.

colorAxis.maxValue

number

Maximum value of color column in chart data

If present, specifies a maximum value for chart color data. Color data values of this value and higher will be rendered as the last color in the colorAxis.colors range.

colorAxis.values

array of numbers

null

If present, controls how values are associated with colors. Each value is associated with the corresponding color in the colorAxis.colors array. These values apply to the chart color data. Coloring is done according to a gradient of the values specified here. Not specifying a value for this option is equivalent to specifying [minValue, maxValue].

colorAxis.colors

array of color strings

null

Colors to assign to values in the visualization. An array of strings, where each element is an HTML color string, for example: colorAxis: {colors:['red','#004411']}. You must have at least two values; the gradient will include all your values, plus calculated intermediary values, with the first color as the smallest value, and the last color as the highest.

datalessRegionColor

string

'F5F5F5'

Color to assign to regions with no associated data.

displayMode

string

'auto'

Which type of geochart this is. The DataTable format must match the value specified. The following values are supported:

'auto' - Choose based on the format of the DataTable.

'regions' - Color the regions on the geochart.

'markers' - Place markers on the regions.

'text' - Label the regions with text from the DataTable.

domain

string

null

Show the geochart as though it were being served from this
region. For instance, setting domain
to 'IN' will display Kashmir as belonging to India
rather than as a disputed territory.

enableRegionInteractivity

boolean

automatic

If true, enable region interactivity, including focus and tool-tip elaboration on mouse hover, and region selection and firing of regionClick and select events on mouse click.

The default is true in region mode, and false in marker mode.

forceIFrame

boolean

false

Draws the chart inside an inline frame. (Note that on IE8, this option is ignored; all IE8 charts are drawn in i-frames.)

height

number

auto

Height of the visualization, in pixels. The default height is 347 pixels, unless the width option is specified and keepAspectRatio is set to true - in which case the height is calculated accordingly.

keepAspectRatio

boolean

true

If true, the geochart will be drawn at the largest size that can fit inside the chart area at its natural aspect ratio. If only one of the width and height options is specified, the other one will be calculated according to the aspect ratio.

If false, the geochart will be stretched to the exact size of the chart as specified by the width and height options.

legend

Object / 'none'

null

An object with members to configure various aspects of the legend, or 'none', if no legend should appear. To specify properties of this object, you can use object literal notation, as shown here:

{textStyle: {color: 'blue', fontSize: 16}}

legend.numberFormat

string

auto

A format string for numeric labels. This is a subset of the ICU pattern set. For instance, {numberFormat:'.##'} will display values "10.66", "10.6", and "10.0" for values 10.666, 10.6, and 10.

The color can be any HTML color string, for example: 'red' or '#00cc00'.
Also see fontName and fontSize.

tooltip.trigger

string

'focus'

The user interaction that causes the tooltip to be displayed:

'focus' - The tooltip will be displayed when the user hovers over the element.

'none' - The tooltip will not be displayed.

'selection' - The tooltip will be displayed when the user selects the element.

width

number

auto

Width of the visualization, in pixels. The default width is 556 pixels, unless the height option is specified and keepAspectRatio is set to true - in which case the width is calculated accordingly.

Continent Hierarchy and Codes

It is possible to show geocharts of continents/sub-continents by setting the region option to one of the following 3-digit codes.
The codes and the hierarchy are based, with some exceptions, on those developed and maintained by the United Nations Statistics Division.

Returns an array of the selected chart entities.
Selectable entities are regions with an assigned value.
For this chart, only one entity can be selected at any given moment.
Extended description.

setSelection()

none

Selects the specified chart entities. Cancels any previous selection.
Selectable entities are regions with an assigned value.
For this chart, only one entity can be selected at a time.
Extended description.

Events

Name

Description

Properties

error

Fired when an error occurs when attempting to render the chart.

id, message

ready

The chart is ready for external method calls. If you want to interact with
the chart, and call methods after you draw it, you should set up a listener
for this event before you call the draw method, and call
them only after the event was fired.

None

regionClick

Called when a region is clicked. This will not be thrown for the specific country
assigned in the 'region' option (if a specific country was listed).

An object with a single property, region, that is a string
in ISO-3166 format describing the region clicked.

select

Fired when the user clicks a visual entity.
To learn what has been selected, call getSelection().

None

Data policy

Locations are geocoded by Google Maps. Any data that does not require geocoding is not sent to any server.
Please see the Google Maps Terms of Service
for more information on their data policy.