YouPrep documentationHelp centerGet a demo

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.

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).

⭐ 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.

Configuration

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 for detailed guidance on how to prepare your dataset for this purpose.

🎥 How to get started

Step-by-Step Configuration

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.

Configuration Fields Explained

*Mandatory parameters

Section
Option
Configuration Tutorial

Dataset*

Select the dataset used by the chart

Zone

Color zones

This allows to apply a color in geographical zones depending on a value. Configure the fields (mandatory: Label and Color value)

Zone

Color zones / Label

Select the column contaning zone labels

Zone

Color zones / color value

Select the column contaning zone colors

Zone

Color zones / Default selected zone

Enter the default selected zone among "first", "last" or the label within the dataset

Zone

Color zones / Zone opacity

Enter the opacity value between 0 and 1 (0 is completely transparent, the default value is set as 1)

Zone

Color zones / Use scaling on unfiltered dataset

Activate the option by clicking on the toogle

Zone

Color zones / Number of scale's buckets

Enter the number of buckets for the scale

Zone

Color zones / Display values on zones

Activate the option in order to display values on zones

Zone

Color zones / Custom color thresholds

Check the box Add threshold value(s) (limited at 3)

Zone

Color zones / Additional info

Check the box Select column(s) of the dataset containing additional info

Zone

Color zones / Scale

Check the box Customize color by clicking on it You can also add new bounds

Zone

Color zones / Reverse scale

Activate this option to set high values as cold and low ones as hot

Zone

Color zones / Missing data zones

Manage the display of zones with no data

Markers

Markers

It allows to apply markers (circle) on some location based on latitude, and longitude. Configure the fields

Markers

Markers / Latitude

Select the column containing latitude coordinates

Markers

Markers / Longitude

Select the column containing Longitude coordinates

Markers

Markers / Label

Select the dataset's column containing markers label

Markers

Markers / Markers color

Select the dataset's column contaning markers color

Markers

Markers /Markers size

Check the box Select the configuration type Customize the size according the configuration type

Markers

Markers / Opacity

Enter the opacity value between 0 and 1 (0 is completely transparent, the default value is set as 1)

Markers

Markers / Additional info

Check the box Select column(s) of the dataset containing additional info

Markers

Markers / Default selected marker

Enter the default selected marker among "first", "last" or the label within the dataset

Markers

Markers / Recycle groups colors

Activate the option to recycle groups colors when chart data changes

Legend

Display legend

It allows to display a legend on the right part of the chart. Click on the checkbox. (You can display the legend of all labels by activating the option "Use exhaustive legend")

Map Background

Background

It allows to display a map as a background. Click on the checkbox Click on the checkbox "Background type" and select the type of background

Map Background

Projection

This is an advanced option (know more about map projection here). By default, the Mercator projection (WGS 84) is assumed. If geographical coordinates in your data are already projected on a plan, set the projection option to the value "plan".

Display

Fixed Map

Activate the option the option to prevent user from zooming within the map

Display

Size

(Used only for multiple charts)

Enter a proportion of the total screen between 0 and 1

Display

Mobile size

(Used only for multiple charts)

Enter a proportion of the total screen between 0 and 1 for mobile screens

Display

Custom CSS Class

Set a custom CSS class to target this specific chart with CSS

Tutorial

ID

Enter an ID.

Change the ID to display the tutorial again.

All tutorials with the same ID will be displayed only once

FAQ

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

Last updated

Was this helpful?