# Choropleth

To learn more about choropleth charts and how to create one, please view this [video](https://youtu.be/Sx16y__xi7U?si=9-t25o7s9b3VA52V).

The Choropleth lets you compare values by geographic region.

| Features                                                           | Quantity | Notes                                                                                             |
| ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------- |
| Required [Dimensions](/immerse/measures-and-dimensions#dimensions) | 1        | Geographic dimension of Countries, States in the United States, or Counties in the United States. |
| Required [Measures](/immerse/measures-and-dimensions#measures)     | 1-2      | Measure 1 = color.                                                                                |

Choropleth comes from the Greek *choros* (area) and *pleth* (multitude). Immerse colors in the map regions based on the measure you choose.

Use a Choropleth to compare aggregate values across regions. Choropleths are useful for spotting outliers but are not intended to provide details on the values within a region. (For detailed, point-level geographic information, consider using a [Pointmap](/immerse/immerse-chart-types/pointmap).)

The Choropleth is available both as a [browser-rendered](/immerse/immerse-chart-types/choropleth#browser-rendered-choropleth-example) chart for CPU and distributed systems and a [server-rendered](/immerse/immerse-chart-types/choropleth#server-rendered-choropleth-example) chart for non-distributed GPU systems that provides additional capabilities.

### Geo JSON Join

Geo JSON Join is used for browser-rendered Choropleths to link geographic shape information to the geographic names in your dataset.

When you assign a map overlay, the region names in the dataset column you select must match the names in the overlay. The column you choose can spell out the name of the region, or use a standard abbreviation, but cannot use both.

For countries, you can use a dataset column with a two- or three-character abbreviation, or one that spells out the full name. See [Country Abbreviations](https://www.nationsonline.org/oneworld/country_code_list.htm).

For US states, you can choose a column with either the full name or the two-character abbreviation. See [US State Abbreviations](https://pe.usps.com/text/pub28/28apb.htm).

The list of US county names can be found in the [List of United States Counties and County equivalents](https://en.wikipedia.org/wiki/List_of_United_States_counties_and_county_equivalents).

### Color Palette

You can choose one of four quantitative gradients to represent the relative values for each area in the Choropleth.

### Custom Measure Formatting

You can use custom measure formats for the values in your chart. See [Customizing Measure and Date Formats](/immerse/measures-and-dimensions#customize-formats).

### Chart Popup Information

When you hover over a server-rendered Choropleth chart, a popup box appears that contains the column information for the highlighted area. You can copy this information to the clipboard. If the column information includes a URL, you can click the URL to open it in a browser.

![](https://files.buildwithfern.com/heavyai.docs.buildwithfern.com/heavyai/47c2f1c58aa057c9aee1d5394e5ea0fea89663c6e62bc1f2ef13e84a0c38aadf/docs/assets/3_choropleth-popup-1-1-2-2-2-2-2.png)

## Browser-rendered Choropleth Example

Create a new Choropleth. Choose a **Data Source**. This example graphs employment statistics for all 50 United States for the years 1980-2015. The data is available at the [University of Kentucky website](http://ukcpr.org/resources/national-welfare-data).

Set the **Dimension** to *state\_name* and the **Color** measure to average *Employment*. Set **GEO JSON JOIN** to *US State* to overlay the defined geo json shapes onto the map.

![](https://files.buildwithfern.com/heavyai.docs.buildwithfern.com/heavyai/4b3b3bb3c76fecd5a8e24b66b9c9281eb3d6cbee04d803446853bbf268adfbd1/docs/assets/3_choropleth-1-3-3-3-2-1-4-2.png)

## Server-rendered Choropleth Example

OmniSci running with GPUs provides additional flexibility for the data files and the ability to create a [multi-layer chart](/immerse/multilayer-charts).

<Info>
  If you are using a distributed configuration, you must propagate the Geo Join tables to all OmniSci servers in the cluster. You can use the Replicate Table checkbox to copy the tables to all servers on import. See [Importing Geospatial Data Using OmniSci Immerse](/loading-and-exporting-data/supported-data-sources/import-geo).
</Info>

This example uses building footprint data for all of the structures in New York City. The data is available at the [NYC Open Data](https://data.cityofnewyork.us/browse?q=building%20footprints\&sortBy=relevance) website.

Create a new Choropleth and select the ORNL\_USA\_BUILDINGS\_NY dataset. Choose *geom* as the Geo measure. Choose *HEIGHT* as the **Color** measure. Set the **MAP THEME** to *Dark* to make the shapes stand out more clearly. Change the **COLOR PALETTE** to the blue-to-red spectrum. The tallest buildings are now displayed in red, and the shortest in blue.

![](https://files.buildwithfern.com/heavyai.docs.buildwithfern.com/heavyai/e17ac36cc9e5c4724dab3f060bd18e42f93d07dc382a3aae17666936770b6830/docs/assets/Choropleth-1.png)

Click **+Add Layer**. Set the **Geo** field to *geom* once again, then set the **Color** measure to *SQFEET*. Change the **COLOR PALETTE** to the blue-to-red spectrum. The largest buildings are now displayed in red.

![](https://files.buildwithfern.com/heavyai.docs.buildwithfern.com/heavyai/7d9730713fecab11c1446220b92d82e4a2ce64b957d4338c6b7ccf93c25d9cfb/docs/assets/choropleth-2.png)

Click the **Master** layer tab. Adjust **LAYER 2 OPACITY** to *50*. Now, the tallest, largest buildings show bright red.

![](https://files.buildwithfern.com/heavyai.docs.buildwithfern.com/heavyai/087f4abb275cc2176d244a9930db1f446a946946d5f3d9055243aae33f223fb8/docs/assets/Choropleth-3.png)