Docs Menu
Docs Home
Atlas Charts
/ /

Choropleth Chart

On this page

  • Regions
  • Choropleth Chart Encoding Channels
  • Use Cases
  • Customization Options
  • Examples
  • Limitations

Choropleth charts are maps that use shading to depict differences across regions. The shading of a region (e.g. states, countries) is based on an aggregated value and is proportional to the corresponding value of other regions.

Unlike other geospatial charts, choropleths do not require coordinate data in your collections. Instead you can have names of regions as strings, so long as the region strings correspond to the names used in a supported Shape Scheme.

To help define regions, Atlas Charts provides Shape Schemes. For example, with the US States scheme, you can define regions at a state level, and your location field value must be one of the 50 states.

Choropleth charts use the following encoding channels:

Encoding Channel

Defines the regions to be shaded on the map.

The value must match (case insensitive) a region value for the selected Shape Scheme. For example, when using the US States scheme, the region of California matches california and CA as well as California.

For a complete list of shape schemes and their expected values, refer to the Shape Schemes page.

Defines the Aggregation that determines the shading of the corresponding Location. You can customize the range of colors that corresponds to the relative aggregated values.

Choropleth charts can be used to depict differences in your selected aggregated field between geographic subregions, such as states or countries. They are useful when you have a dataset with clearly defined subregions compatible with one of the Shape Schemes Atlas Charts provides.

A choropleth chart is a good choice to compare:

  • Population density across US states.

  • Annual rainfall across European countries.

  • Number of cellphone towers across Australian states.


See also:

If you are looking for a chart to depict exact values rather than a high-level comparison, consider using a Table.

The following customization options are specific to choropleth charts. For general customization options, see Customize Charts.

By default, geospatial charts show a map which includes all the data point markers in your specified collection. You can pan and zoom to change the map view, but if you close the chart and re-open it the map reverts to its default state. This behavior is controlled by the Automatically Set Viewport option.

When you toggle the Automatically Set Viewport switch to Off, the area and zoom level at which the map is saved becomes the new default view.


You can pan and zoom the map area in a chart on a dashboard, but these changes do not affect the default map view.

The Opacity level of a map modifies the degree to which the chart's map data shows through the data point markers.

Choropleth charts default to 100%.

The color palette specifies the range of colors that corresponds to relative aggregated values in your map. Choropleth charts use a gradient color picker.

To enable palette customization, toggle the Custom Color Palette switch in the General section.

For more information, see Color Palette Customization.

The following choropleth chart visualizes the total count of movie releases across various countries. Each document in the collection contains an array of countries where a particular movie was released.

Choropleth example chart

In this chart, we specify a Shape Scheme of World Countries to divide the map into countries.

The countries array in the Location field contains an array of elements representing each country where a movie was released. These elements match the values expected by the World Countries shape scheme. We unwind the array so each movie contributes to the count for each country where it was released.

The Color field of id is aggregated by Count. As a result, each country is shaded based on its number of movies released.

The custom color palatte for this chart ranges from yellow for lower ratings to dark red for higher ratings. Based on the visualization, we see that France, India, and Japan have relatively high movie release counts compared with other countries.


See also:

For a complete list of choropleth Shape Schemes and their expected values, refer to the Choropleth Regions page.

The maximum query response size for a choropleth chart is 5000 documents.

← Geospatial Charts