# Visualization: Geomap

1. [Overview](https://developers.google.com/chart/interactive/docs/gallery/geomap#Overview)
2. [Examples](https://developers.google.com/chart/interactive/docs/gallery/geomap#Example)
3. [Loading](https://developers.google.com/chart/interactive/docs/gallery/geomap#Loading)
4. [Data Format](https://developers.google.com/chart/interactive/docs/gallery/geomap#Data_Format)
5. [Configuration Options](https://developers.google.com/chart/interactive/docs/gallery/geomap#Configuration_Options)
6. [Methods](https://developers.google.com/chart/interactive/docs/gallery/geomap#Methods)
7. [Events](https://developers.google.com/chart/interactive/docs/gallery/geomap#Events)
8. [Data Policy](https://developers.google.com/chart/interactive/docs/gallery/geomap#Data_Policy)
9. [Notes](https://developers.google.com/chart/interactive/docs/gallery/geomap#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](https://developers.google.com/chart/interactive/docs/gallery/geomap#regionsexample), and another that uses the [markers
display style](https://developers.google.com/chart/interactive/docs/gallery/geomap#markersexample).

### 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.
\<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"\>\</script\> \<div id="regions_div" style="width: 900px; height: 500px;"\>\</div\> 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); };

```html
<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](http://en.wikipedia.org/wiki/ISO_3166-1) code or its English text equivalent (for example, "GB" or "United Kingdom").
     - An uppercase [ISO-3166-2](http://en.wikipedia.org/wiki/ISO_3166-1) 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](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions). 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](http://en.wikipedia.org/wiki/ISO_3166-1) 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 `https://developers.google.com/chart/interactive/docs/gallery/geomap#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](https://developers.google.com/chart/interactive/docs/gallery/geomap#regionsexample). - `markers` - Displays a dot over a region, with the color and size indicating the value. See [Markers Example](https://developers.google.com/chart/interactive/docs/gallery/geomap#markersexample). |
| `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 `https://developers.google.com/chart/interactive/docs/gallery/geomap#zoomoutevent` 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()`](https://developers.google.com/chart/interactive/docs/reference#visgetselection) 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 `https://developers.google.com/chart/interactive/docs/reference#vissetselection` 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()`](https://developers.google.com/chart/interactive/docs/gallery/geomap#Methods). 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](https://developers.google.com/maps/terms)
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](http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager02.html).