﻿---
title: Build region map charts with Kibana
description: Instructions and best practices for building region map charts with Kibana Lens in Elastic.
url: https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/visualize/charts/region-map-charts
products:
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available
---

# Build region map charts with Kibana
Region map charts display data on a geographic map, using colors to represent values for different regions such as countries, states, or provinces. They are ideal for showing geographic distributions, comparing metrics across locations, and identifying regional patterns in your data.
You can create region map charts in Kibana using [**Lens**](https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/visualize/lens).
![Example Lens region map chart](https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/images/region-map-chart-example.png)

## Build a region map chart

Before you start, make sure you have data [indexed into Elasticsearch](https://www.elastic.co/elastic/docs-builder/docs/2989/manage-data/ingest) or [install sample data](https://www.elastic.co/elastic/docs-builder/docs/2989/manage-data/ingest/sample-data). By default, Lens uses [data views](https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/find-and-organize/data-views) to access your Elasticsearch data. Data views are created automatically in most cases when you ingest data. You can also [create one manually](https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/find-and-organize/data-views) to select just the data that you want. Alternatively, you can use the [ES|QL query mode](https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/visualize/esorql) to query your Elasticsearch data directly.
To build a region map chart:
<stepper>
  <step title="Access Lens">
    **Lens** is Kibana's main visualization editor. You can access it:
    - From a dashboard: On the **Dashboards** page, open or create the dashboard where you want to add a region map chart, then add a new visualization.
    - From the **Visualize library** page by creating a new visualization.
  </step>

  <step title="Set the visualization to Region map">
    New visualizations often start as **Bar** charts.Using the **Visualization type** dropdown, select **Region map**.
  </step>

  <step title="Define the data to show">
    1. Select the data view that contains your data.
    2. Configure the [**Region key**](#region-key-settings) dimension to define which geographic field to use. This field should contain region codes (ISO country codes, state abbreviations, and more) that can be matched to map boundaries.
    3. Configure the [**Metric**](#metric-settings) dimension to define the value displayed for each region. This determines the color intensity.
    The chart preview updates to show a map with regions colored by metric value. If regions appear gray, verify that your field values match the expected geographic codes (such as ISO country codes). Also check that the correct EMS boundaries and join field are selected in the Region key dimension settings.
  </step>

  <step title="Customize the chart to follow best practices">
    Tweak the appearance of the chart to your needs. Consider the following best practices:
    <definitions>
      <definition term="Use appropriate region granularity">
        Match the EMS boundaries to your data. For example, use the World Countries boundaries for global data, or a country-specific boundary set for more granular regional analysis.
      </definition>
      <definition term="Select the correct join field">
        Ensure your data values match the selected [join field](#region-key-settings). For example, if your data contains two-letter country codes, select the `iso2` join field.
      </definition>
      <definition term="Handle missing regions">
        Regions with no matching data appear gray. If too many regions are gray, verify that your field values match the selected join field format.
      </definition>
      <definition term="Consider choropleth best practices">
        Region maps are choropleth maps, where color represents data values. Be aware that larger regions can visually dominate, even if their values are smaller.
      </definition>
    </definitions>
    Refer to [Region map chart settings](#region-map-chart-settings) to find all configuration options for your region map chart.
  </step>

  <step title="Save the chart">
    - If you accessed Lens from a dashboard, select **Save and return** to save the visualization and add it to that dashboard, or select **Save to library** to add the visualization to the Visualize library and reuse it later.
    - If you accessed Lens from the Visualize library, select **Save**. A menu opens and lets you add the visualization to a dashboard and to the Visualize library.
  </step>
</stepper>


## Region map chart settings

Customize your region map chart to display exactly the information you need, formatted the way you want.

### Region key settings

The **Region key** dimension defines which geographic areas to display on the map.
<definitions>
  <definition term="Data">
    The **Region key** dimension supports the following functions:
    - **Top values**: Display the regions with the highest metric values.
      - **Field**: Select the field containing geographic identifiers to group by.
    - **Number of values**: How many regions to display.
      - **Rank by**: Specifies the dimension the top values are ranked by. Available options:
      - **Count of records**: Rank by the number of documents containing each value. This is the default when a metric is defined.
      - **Alphabetical**: Rank by the term key alphabetically. This is the default when no metric is defined.
      - **Rarity**: Find terms that appear in very few documents, using a [rare terms aggregation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2989/reference/aggregations/search-aggregations-bucket-rare-terms-aggregation). You can configure the **Max doc count** to set the maximum number of documents a term can appear in to be considered rare (default: 1, max: 100). Only available for non-numeric fields and single-field terms.
      - **Significance**: Find statistically unusual terms compared to the overall data set, using a [significant terms aggregation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2989/reference/aggregations/search-aggregations-bucket-significantterms-aggregation). Only available for `keyword` fields and single-field terms.
      - **Custom**: Define a custom metric aggregation to rank by (for example, rank by the sum of a numeric field rather than by count).
      - **Rank direction**: Ascending or descending order. Disabled when **Rank by** is set to **Rarity** or **Significance**.
      <dropdown title="Advanced settings">
      Several advanced options allow you to refine the behavior of the breakdown:
      - **Include documents without the selected field**: Off by default.
      - **Group remaining values as "Other"**: On by default.
      - **Enable accuracy mode**: This option improves results for high-cardinality data, but increases the load on the Elasticsearch cluster.
      - **Include values**: Values from the breakdown dimension to always show a tile for.
      - **Exclude values**: Values from the breakdown dimension to always exclude from the displayed tiles.
      </dropdown>
    - **Filters**: Define custom KQL filters to create specific regions.
  </definition>
  <definition term="EMS boundaries">
    Select the geographic boundary shapes to use for the map. The Elastic Maps Service (EMS) provides boundary data that defines region outlines. For example, **World Countries** provides country polygons, while **US States** provides state polygons. Other boundary sets may be available based on your EMS configuration.
  </definition>
  <definition term="Join field">
    Select which property of the boundary shapes to use for matching your data. Each boundary set exposes one or more properties that can be used to link your region key values to the correct shape on the map. For example, the World Countries boundaries can be matched by two-letter ISO country code (`iso2`), three-letter code (`iso3`), or country name. Select the property that matches the format of your data.
    For instance, if your data contains values like `US`, `GB`, `DE`, select the `iso2` join field. If it contains values like `United States`, `United Kingdom`, select the country name join field instead.
  </definition>
  <definition term="Appearance">
    - **Name**: Customize the region label displayed in tooltips.
  </definition>
</definitions>


### Metric settings

The **Metric** dimension defines the value that determines each region's color.
<definitions>
  <definition term="Data">
    The value that determines region color intensity. When you drag a field onto the chart, Kibana suggests a function based on the field type. You can use aggregation functions like `Sum`, `Average`, `Count`, `Median`, and more, or create custom calculations with [formulas](/elastic/docs-builder/docs/2989/explore-analyze/visualize/lens#lens-formulas).
    <dropdown title="Advanced settings">
      Depending on the data you defined, several options allow you to apply additional filtering to the data taken into account to compute the final value to show.Based on the type of visualization you're creating, only some of the following options can be available:
      - **Normalize by unit**: Normalize the metric values to show per unit of time.
      - **Filter by**: Specify a query.
      - **Reduced time range**: Reduce the time range specified on the dashboard's time filter by the specified duration.
      - **Time shift**: Shift the time range by the specified duration. This is useful if the value should use a different time range than the one selected on the dashboard.
      - **Hide zero values**: Don't show values equal to zero. This option is on by default.
    </dropdown>
  </definition>
  <definition term="Appearance">
    - **Name**: Customize the metric label displayed in tooltips.
    - **Value format**: Control how numeric values are displayed (number, percent, bytes, and more).
  </definition>
</definitions>


## Region map chart examples

The following examples show various configuration options for building impactful region map charts.
<definitions>
  <definition term="Website traffic by destination country">
    Visualize which countries receive the most web traffic:
    - Example based on: Kibana Sample Data Logs
    - **Region key**: `geo.dest` (Top values)
    - **EMS boundaries**: World Countries
    - **Metric**: Count
  </definition>
</definitions>

![Region map showing website traffic by destination country](https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/images/region-map-example-traffic.png)
<definitions>
  <definition term="Customer distribution by country">
    Show where your customers are located around the world:
    - Example based on: Kibana Sample Data eCommerce
    - **Region key**: `geoip.country_iso_code` (Top 50 values)
    - **EMS boundaries**: World Countries
    - **Metric**: Unique count of `customer_id`
  </definition>
</definitions>

![Region map showing customer distribution by country](https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/images/region-map-example-customers.png)
<definitions>
  <definition term="Average ticket price by destination country">
    Compare average flight ticket prices across destination countries:
    - Example based on: Kibana Sample Data Flights
    - **Region key**: `DestCountry` (Top 50 values)
    - **EMS boundaries**: World Countries
    - **Metric**: Average of `AvgTicketPrice`
  </definition>
</definitions>

![Region map showing average ticket price by destination country](https://www.elastic.co/elastic/docs-builder/docs/2989/explore-analyze/images/region-map-example-ticket-price.png)