Visualization: Geomap

Overview
Examples
Loading
Data Format
Configuration Options
Methods
Events
Data Policy
Notes

Overview

A geomap is a map of a country, continent, or region map, with colors and values assigned to specific regions. Values are displayed as a color scale, and you can specify optional hovertext for regions. The map is rendered in the browser using an embedded Flash player. Note that the map is not scrollable or draggable, but can be configured to allow zooming.

Examples

We have two examples here: one that uses the regions display style, and another that uses the markers display style.

Regions Example

The regions style fills entire regions (typically countries) with colors corresponding to the values that you assign. Specify the regions style by assigning options['dataMode'] = 'regions' in your code.

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">
      google.charts.load('current', {
        'packages':['geomap'],
        // Note: you will need to get a mapsApiKey for your project.
        // See: https://developers.google.com/chart/interactive/docs/basic_load_libs#load-settings
        'mapsApiKey': 'AIzaSyD-9tSrke72PouQMnMX-a7eZSW0jkFMBWY'
      });
      google.charts.setOnLoadCallback(drawMap);

      function drawMap() {
        var data = google.visualization.arrayToDataTable([
          ['Country', 'Popularity'],
          ['Germany', 200],
          ['United States', 300],
          ['Brazil', 400],
          ['Canada', 500],
          ['France', 600],
          ['RU', 700]
        ]);

        var options = {};
        options['dataMode'] = 'regions';

        var container = document.getElementById('regions_div');
        var geomap = new google.visualization.GeoMap(container);

        geomap.draw(data, options);
      };
    </script>
  </head>
  <body>
    <div id="regions_div" style="width: 900px; height: 500px;"></div>
  </body>
</html>

Markers Example

The "markers" style displays a circle, sized and colored to indicate a value, over the regions that you specify.

<html>
<head>
  <script type='text/javascript' src='https://www.gstatic.com/charts/loader.js'></script>
  <script type='text/javascript'>
   google.charts.load('current', {'packages': ['geomap']});
   google.charts.setOnLoadCallback(drawMap);

    function drawMap() {
      var data = google.visualization.arrayToDataTable([
        ['City', 'Popularity'],
        ['New York', 200],
        ['Boston', 300],
        ['Miami', 400],
        ['Chicago', 500],
        ['Los Angeles', 600],
        ['Houston', 700]
      ]);

      var options = {};
      options['region'] = 'US';
      options['colors'] = [0xFF8747, 0xFFB581, 0xc06000]; //orange colors
      options['dataMode'] = 'markers';

      var container = document.getElementById('map_canvas');
      var geomap = new google.visualization.GeoMap(container);
      geomap.draw(data, options);
    };

  </script>
</head>

<body>
    <div id='map_canvas'></div>
</body>

</html>

Loading

The google.charts.load package name is "geomap"

  google.charts.load('current', {'packages': ['geomap']});

The geomap visualization class name is google.visualization.GeoMap

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

Data Format

Two address formats are supported, each of which supports a different number of columns, and different data types for each column. All addresses in the table must use one or the other; you cannot mix types.

Format 1: Latitude/Longitude locations. This format works only when the dataMode option is 'markers'. If this format is used, you do not need to include the Google Map Javascript. The location is entered in two columns, plus two optional columns:
1. [Number, Required] A latitude. Positive numbers are north, negative numbers are south.
2. [Number, Required] A longitude. Positive numbers are east, negative numbers are west.
3. [Number, Optional] A numeric value displayed when the user hovers over this region. If column 4 is used, this column is required.
4. [String, Optional] Additional string text displayed when the user hovers over this region.
Format 2: Address, country name, region name locations, or US metropolitan area codes. This format works with the dataMode option set to either 'markers' or 'regions'. The location is entered in one column, plus two optional columns:
1. [String, Required] A map location. The following formats are accepted:
  - A specific address (for example, "1600 Pennsylvania Ave").
  - A country name as a string (for example, "England"), or an uppercase ISO-3166 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"). Note: Regions can only be specified when the dataMode option is set to 'regions'.
  - 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.
2. [Number, Optional] A numeric value displayed when the user hovers over this region. If column 3 is used, this column is required.
3. [String, Optional] Additional string text displayed when the user hovers over this region.

Note: A map can display a maximum of 400 entries; if your DataTable or DataView holds more than 400 rows, only the first 400 will be shown. The fastest modes are dataMode='regions' with locations specified as ISO codes, and dataMode='markers' with lat/long enties. The slowest mode is dataMode='markers' with a string address.

Important: Your DataTable must include every optional column preceding any column that you want to use. So, for example, if you want to specify a lat/long table, and only wanted to use columns 1, 2, and 4, your DataTable must still define column 3 (though you don't need to add any values to it):

dataTable = new google.visualization.DataTable();
dataTable.addRows(1);
dataTable.addColumn('number', 'LATITUDE', 'Latitude');
dataTable.addColumn('number', 'LONGITUDE', 'Longitude');
dataTable.addColumn('number', 'VALUE', 'Value'); // Won't use this column, but still must define it.
dataTable.addColumn('string', 'HOVER', 'HoverText');

dataTable.setValue(0,0,47.00);
dataTable.setValue(0,1,-122.00);
dataTable.setValue(0,3,"Hello World!");

Configuration Options

Name	Type	Default	Description
`region`	string	'world'	The area to display on the map. (Surrounding areas will be displayed as well.) Can be either a country code (in uppercase ISO-3166 format), or a one of the following strings: `world` - (Whole world) `us_metro` - (United States, metro areas) `005` - (South America) `013` - (Central America) `021` - (North America) `002` - (All of Africa) `017` - (Central Africa) `015` - (Northern Africa) `018` - (Southern Africa) `030` - (Eastern Asia) `034` - (Southern Asia) `035` - (Asia/Pacific region) `009` - (Oceania) `145` - (Middle East) `143` - (Central Asia) `151` - (Northern Asia) `154` - (Northern Europe) `155` - (Western Europe) `039` - (Southern Europe) Geomap does not enable scrolling or dragging behavior, and only limited zooming behavior. A basic zoom out can be enabled by setting the `showZoomOut` property.
`dataMode`	string	'regions'	How to display values on the map. Two values are supported: `regions` - Colors a whole region with the appropriate color. This option cannot be used with latitude/longitude addresses. See Regions Example. `markers` - Displays a dot over a region, with the color and size indicating the value. See Markers Example.
`width`	string	'556px'	Width of the visualization. If no units are given, the default unit is pixels.
`height`	string	'347px'	Height of the visualization. If no units are given, the default unit is pixels.
`colors`	Array of RGB numbers in the format 0xRRGGBB	[0xE0FFD4, 0xA5EF63, 0x50AA00, 0x267114]	Color gradient to assign to values in the visualization. You must have at least two values; the gradient will include all your values, plus calculated intermediary values, with the lightest color as the smallest value, and the darkest color as the highest.
`showLegend`	boolean	true	If true, display a legend for the map.
`showZoomOut`	boolean	false	If true, display a button with the label specified by the `zoomOutLabel` property. Note that this button does nothing when clicked, except throw the `zoomOut` event. To handle zooming, catch this event and change the `region` option. You can only specify `showZoomOut` if the `region` option is smaller than the world view. One way of enabling zoom in behavior would be to listen for the `regionClick` event, change the `region` property to the appropriate region, and reload the map.
`zoomOutLabel`	string	'Zoom Out'	Label for the zoom button.

Methods

Method	Return Type	Description
`draw(data, options)`	None	Draws the map. Can return before drawing is done (see `drawingDone()` event).
`getSelection()`	Array of selection elements	Standard `getSelection()` implementation. Selected elements are rows. This method only works when the `dataMode` option is 'regions'. You can only select a region with an assigned value.
`setSelection(selection)`	None	Standard `setSelection()` implementation. Treats a selection as a row selection, and supports multiple row selections. Only regions with assigned values can be selected.

Events

Name	Description	Properties
`error`	Fired when an error occurs when attempting to render the chart.	id, message
`select`	Fired when the user clicks a region with an assigned value. To learn what has been selected, call `getSelection()`. Available only when the `dataMode` option is set to 'regions'. Note: Because of certain limitations, the `select` event is not thrown if you are accessing the page in your browser as a file (e.g., "file://") rather than from a server (e.g., "http://www").	None
`regionClick`	Called when a region is clicked. Works both for 'regions' and 'markers' `dataMode`. However, in marker mode, this will not be thrown for the specific country assigned in the 'region' option (if a specific country was listed). Note: Because of certain limitations, the `regionClick` event is not thrown if you are accessing the page in your browser as a file (e.g., "file://") rather than from a server (e.g., "http://www").	An object with a single property, `region`, that is a string in ISO-3166 format describing the region clicked.
`zoomOut`	Called when the zoom out button is clicked. To handle zooming, catch this event and change the `region` option. Note: Because of certain limitations, the `zoomOut` event is not thrown if you are accessing the page in your browser as a file (e.g., "file://") rather than from a server (e.g., "http://www").	None
`drawingDone`	Called when the geomap has finished drawing.	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.

Notes

Because of Flash security settings, this (and all Flash-based visualizations) might not work correctly when accessed from a file location in the browser (e.g., file:///c:/webhost/myhost/myviz.html) rather than from a web server URL (e.g., http://www.myhost.com/myviz.html). This is typically a testing issue only. You can overcome this issue as described on the Macromedia web site.