# Mapchart

## 🧭 Overview

The **Map Chart** allows you to visualize data on a geographical map by combining a dataset with a GeoJSON file.\
It is particularly useful for:

* Displaying KPIs per region, department, or country.
* Visualizing demographic or economic data (e.g. population, accidents, sales).
* Providing drill-down analysis from continent → country → region.

{% hint style="info" %}
**Requirements:**

* A **GeoJSON file** containing geometry coordinates (shapes of areas) and at least one identifier (e.g. region code).
* A **dataset** with measures (e.g. population) and dimensions (e.g. department code) that can be matched to the GeoJSON.
* Clean and consistent join keys (e.g. `"01"` vs `1` → both formatted the same).
  {% endhint %}

## ⭐ Key features

* **Zone coloring**: Assign colors to map areas based on metrics.
* **Markers**: Place points on the map using longitude/latitude coordinates.
* **Drill-down**: Navigate between levels of geography (e.g. continent → country → region).
* **Background maps**: Add a custom basemap (e.g. Mapbox).
* **Legends**: Display exhaustive legends or color scales.
* **Performance options**: Simplify or dissolve shapes to reduce complexity.
* **Customization**: Control opacity, scaling, missing data display.

{% @arcade/embed url="<https://app.arcade.software/share/6lxB2eQhSAMtqZqKS6oh>" flowId="6lxB2eQhSAMtqZqKS6oh" %}

## Configuration

{% hint style="info" %}
To create a Map Chart, your dataset must include a geographical column. This column will be automatically detected and used by the system.

Refer to the [documentation](/data-management-in-datahub/datasets-in-toucan/preparing-data/overview-of-youprep-tm/geo/prepare-geo-data-with-basemap.md) for detailed guidance on how to prepare your dataset for this purpose.
{% endhint %}

**🎥 How to get started**

{% @arcade/embed url="<https://app.arcade.software/share/tjke7tR142GN9dg4aMpZ>" flowId="tjke7tR142GN9dg4aMpZ" %}

<details>

<summary>Step-by-Step Configuration</summary>

**Step 1: Prepare your data**

1. Import your **GeoJSON file** into the DataHub.
   * Ensure the file ends with `.geojson`.
   * Check that it contains a geometry column and an identifier (e.g. `department_code`).
2. Import your **business dataset** (e.g. population by department).
3. Clean the dataset in **U-Prep**:
   * Keep only relevant columns.
   * Convert join keys to the same type (text or integer).
   * Remove null values (they may break the chart).
4. Join the **business dataset** with the **GeoJSON** on the identifier (e.g. `department_code`).
   * Result: one dataset containing geometry + metrics.

***

**Step 2: Create the Map Chart**

1. Go to **Charts** → **New Chart** → Select **Map Chart**.
2. Configure:
   * **Zone (Label):** The area name (e.g. `Department Name`).
   * **Color Zone:** The metric to display (e.g. `Population`).
   * **Label:** Value to display on the map (optional).
   * **Additional Info:** Extra values in tooltips (optional).

***

**Step 3: Adjust display options**

* **Scaling:** Define number of color buckets.
* **Colors:** Set custom colors (currently static).
* **Legend:** Choose exhaustive or filtered legend.
* **Opacity:** Adjust transparency of zones.
* **Missing Data:** Show or hide zones with no data.

***

**Step 4: Advanced options**

* **Markers:** Add longitude/latitude data as points.
* **Drill-down:** Configure hierarchical GeoJSON datasets for multi-level navigation.
* **Background maps:** Use Mapbox or other services for custom styling.
* **Performance tuning:** Simplify or dissolve geometries for faster rendering.

</details>

<details>

<summary>Configuration Fields Explained</summary>

<mark style="color:red;">**\***</mark>**Mandatory parameters**

<table><thead><tr><th width="165.33333333333331">Section</th><th width="226">Option</th><th>Configuration Tutorial</th></tr></thead><tbody><tr><td></td><td>Dataset<mark style="color:red;"><strong>*</strong></mark></td><td>Select the dataset used by the chart</td></tr><tr><td>Zone</td><td>Color zones</td><td>This allows to apply a color in geographical zones depending on a value.<br>Configure the fields (mandatory: Label and Color value)</td></tr><tr><td>Zone</td><td>Color zones / Label</td><td>Select the column contaning zone labels</td></tr><tr><td>Zone</td><td>Color zones / color value</td><td>Select the column contaning zone colors</td></tr><tr><td>Zone</td><td>Color zones / Default selected zone</td><td>Enter the default selected zone among "first", "last" or the label within the dataset</td></tr><tr><td>Zone</td><td>Color zones / Zone opacity</td><td>Enter the opacity value between 0 and 1 (0 is completely transparent, the default value is set as 1)</td></tr><tr><td>Zone</td><td>Color zones / Use scaling on unfiltered dataset</td><td>Activate the option by clicking on the toogle</td></tr><tr><td>Zone</td><td>Color zones / Number of scale's buckets</td><td>Enter the number of buckets for the scale</td></tr><tr><td>Zone</td><td>Color zones / Display values on zones</td><td>Activate the option in order to display values on zones</td></tr><tr><td>Zone</td><td>Color zones / Custom color thresholds</td><td>Check the box<br>Add threshold value(s) (limited at 3)</td></tr><tr><td>Zone</td><td>Color zones / Additional info</td><td>Check the box<br>Select column(s) of the dataset containing additional info</td></tr><tr><td>Zone</td><td>Color zones / Scale</td><td>Check the box<br>Customize color by clicking on it<br>You can also add new bounds</td></tr><tr><td>Zone</td><td>Color zones / Reverse scale</td><td>Activate this option to set high values as cold and low ones as hot</td></tr><tr><td>Zone</td><td>Color zones / Missing data zones</td><td>Manage the display of zones with no data</td></tr><tr><td>Markers</td><td>Markers</td><td>It allows to apply markers (circle) on some location based on latitude, and longitude.<br>Configure the fields</td></tr><tr><td>Markers</td><td>Markers / Latitude</td><td>Select the column containing latitude coordinates</td></tr><tr><td>Markers</td><td>Markers / Longitude</td><td>Select the column containing Longitude coordinates</td></tr><tr><td>Markers</td><td>Markers / Label</td><td>Select the dataset's column containing markers label</td></tr><tr><td>Markers</td><td>Markers / Markers color</td><td>Select the dataset's column contaning markers color</td></tr><tr><td>Markers</td><td>Markers /Markers size</td><td>Check the box<br>Select the configuration type<br>Customize the size according the configuration type</td></tr><tr><td>Markers</td><td>Markers / Opacity</td><td>Enter the opacity value between 0 and 1 (0 is completely transparent, the default value is set as 1)</td></tr><tr><td>Markers</td><td>Markers / Additional info</td><td>Check the box<br>Select column(s) of the dataset containing additional info</td></tr><tr><td>Markers</td><td>Markers / Default selected marker</td><td>Enter the default selected marker among "first", "last" or the label within the dataset</td></tr><tr><td>Markers</td><td>Markers / Recycle groups colors</td><td>Activate the option to recycle groups colors when chart data changes</td></tr><tr><td>Legend</td><td>Display legend</td><td>It allows to display a legend on the right part of the chart.<br>Click on the checkbox.<br>(You can display the legend of all labels by activating the option "Use exhaustive legend")</td></tr><tr><td>Map Background</td><td>Background</td><td>It allows to display a map as a background.<br>Click on the checkbox<br>Click on the checkbox "Background type" and select the type of background</td></tr><tr><td>Map Background</td><td>Projection</td><td>This is an advanced option (know more about map projection <a href="https://en.wikipedia.org/wiki/Map_projection">here</a>).<br>By default, the Mercator projection (<a href="https://epsg.io/3857">WGS 84</a>) is assumed.<br>If geographical coordinates in your data are already projected on a plan, set the projection option to the value "plan".</td></tr><tr><td>Display</td><td>Fixed Map</td><td>Activate the option the option to prevent user from zooming within the map</td></tr><tr><td>Display</td><td>Size</td><td><p>(Used only for multiple charts)</p><p>Enter a proportion of the total screen between 0 and 1</p></td></tr><tr><td>Display</td><td>Mobile size</td><td><p>(Used only for multiple charts)</p><p>Enter a proportion of the total screen between 0 and 1 for mobile screens</p></td></tr><tr><td>Display</td><td>Custom CSS Class</td><td>Set a custom CSS class to target this specific chart with CSS</td></tr><tr><td>Tutorial</td><td>ID</td><td><p>Enter an ID.</p><p>Change the ID to display the tutorial again.</p><p>All tutorials with the same ID will be displayed only once</p></td></tr></tbody></table>

</details>

<details>

<summary>FAQ</summary>

**1. Why doesn’t my Map Chart display?**

* Check that your dataset contains a **geographical column** (from a GeoJSON file).
* Make sure the **join key** (e.g. region code, department code) is of the same type in both datasets (e.g. both as text).
* Remove any **null values** in your dataset — Map Charts cannot render them.

***

**2. What file formats are supported for geographical data?**

* You need a **GeoJSON file** (`.geojson`).
* Ensure the file includes both the **geometry column** (coordinates) and an **identifier** (e.g. `id`, `code`, `region`).

***

**3. Why are some zones not colored on my map?**

* The identifiers in your dataset may not match the identifiers in the GeoJSON (e.g. `1` vs `01`).
* Make sure your join is correct and that the column types are aligned.
* If data is missing, the zone will appear blank (see “Missing Data” option in settings).

***

**4. Can I use markers (points) instead of zones?**

Yes. You can display markers using **longitude and latitude** columns.\
⚠ Note: Legends for markers are limited and may require additional Data Prep to group values into ranges.

***

**5. Can I drill down into different levels (e.g. country → region → department)?**

Yes, but:

* Your dataset must include a **hierarchical GeoJSON** (with multiple levels).
* Configure the drill levels in the chart settings.

***

**6. My map is very slow to load. How can I improve performance?**

* Simplify or dissolve your GeoJSON file (reduce number of coordinates).
* Use fewer details on shapes (e.g. smoother coastlines).
* Aggregate data before loading into the Map Chart.

***

**7. Can I use dynamic color scales?**

Currently, only **static color scales** are supported.

* If you filter or change datasets, the static scale may no longer match.
* For consistency, keep ranges broad or update the scale manually.

***

**8. Why does my map zoom out too far or show strange positioning?**

* Some GeoJSON files include overseas territories (e.g. French DOM-TOM).
* Adjust the **zoom** or reposition these territories manually to improve readability.

***

**9. What are the best practices before creating a Map Chart?**

* Always clean and prepare your dataset in **YouPrep**.
* Ensure consistent join keys.
* Remove nulls.
* Aggregate values beforehand.
* Test your GeoJSON in a viewer (e.g. geojson.io) to confirm structure

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-v3.toucantoco.com/visualizations-and-layouts/creating-visualizations/viz-gallery/legacy-viz-designs/mapchart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.