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.

defaultColor: the color to assign to regions in the datatable for which the value is either null or unspecified.

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 your dataset. If you specify more
than two colors, interpolation will occur between them.

In the following chart, we'll use all four
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, datalessRegionColor to color the
non-African countries a light pink, and defaultColor for
Madagascar.

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

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.

The first two columns are numeric, where the first column is the latitude,
and the second column is the longitude.

Note: Although we recommend ISO 3166 codes to be used for 'regions' mode, 'markers'
mode works best with longer names for regions (like Germany, Panama, etc). This is
because geocharts, when in 'markers' mode, uses
Google Maps for geocoding the locations
(converting a string location to a latitude and longitude). This may result in ambiguous
locations not getting geocoded as you might expect; such as 'DE' standing for Germany or
Delaware, or 'PA' standing for Panama or Pennsylvania.

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

backgroundColor

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.

Type: string or object

Default: white

backgroundColor.fill

The chart fill color, as an HTML color string.

Type: string

Default: white

backgroundColor.stroke

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

Type: string

Default: '#666'

backgroundColor.strokeWidth

The border width, in pixels.

Type: number

Default: 0

colorAxis

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']}

Type: object

Default: null

colorAxis.minValue

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.

Type: number

Default: Minimum value of color column in chart data

colorAxis.maxValue

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.

Type: number

Default: Maximum value of color column in chart data

colorAxis.values

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

Type: array of numbers

Default: null

colorAxis.colors

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.

Type: array of color strings

Default: null

datalessRegionColor

Color to assign to regions with no associated data.

Type: string

Default: '#F5F5F5'

defaultColor

The color to use when for data points in a geochart when the location
(e.g., 'US' ) is present but the value is either null or
unspecified. This is distinct from datalessRegionColor, which is the color
used when data is missing.

Type: string

Default: '#267114'

displayMode

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.

Type: string

Default: 'auto'

domain

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.

Type: string

Default: null

enableRegionInteractivity

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.

Type: boolean

Default: automatic

forceIFrame

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

Type: boolean

Default: false

height

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.

Type: number

Default: auto

keepAspectRatio

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.

Type: boolean

Default: true

legend

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}}

Type: Object / 'none'

Default: null

legend.numberFormat

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.

Type: string

Default: auto

legend.textStyle

An object that specifies the legend text style. The object has this format:

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

Type: string

Default: 'focus'

width

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.

Type: number

Default: auto

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.

Return Type: Array of selection elements

setSelection()

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.

Return Type: none

Events

Name

error

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

Properties: 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.

Properties: 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).

Properties:
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().

Properties: 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.