Hands On

Make a choropleth with qualitative data in XYZ Studio

By Dylan Babbs | 11 September 2019

Try HERE Maps

Create a free API key to build location-aware apps and services.

Get Started

A few months ago, we worked with the HERE Social Media team to produce the map for the Marijuana delivery on-demand sparks controversy in legal states article in our company's blog.

You can see the full version of the map at this link.

In this blog post, we'll present the steps to create a qualitative choropleth map of the legal status of marijuana in the United States with XYZ Studio.

Input data

The map's original data came in CSV (comma-separated format) with just two columns:

  • state name
  • legal status of marijuana (fully legal, medical only, or illegal)

Take a look at the dataset:

Alaska,Fully legal
California,Fully legal
Colorado,Fully legal
Maine,Fully legal
Massachusetts,Fully legal
Michigan,Fully legal
Nevada,Fully legal
Oregon,Fully legal
Vermont,Fully legal
Washington,Fully legal
District of Columbia,Fully legal
Arizona,Medical only
Arkansas,Medical only
Connecticut,Medical only
Delaware,Medical only
Florida,Medical only
Georgia,Medical only
Hawaii,Medical only
Illinois,Medical only
Louisiana,Medical only
Maryland,Medical only
Minnesota,Medical only
Missouri,Medical only
Montana,Medical only
New Hampshire,Medical only
New Jersey,Medical only
New Mexico,Medical only
New York,Medical only
North Dakota,Medical only
Ohio,Medical only
Oklahoma,Medical only
Pennsylvania,Medical only
Rhode Island,Medical only
Utah,Medical only
West Virginia,Medical only
North Carolina,Illegal
South Carolina,Illegal
South Dakota,Illegal

The data set contains information for all 50 states plus the District of Columbia.

Enriching the data with geometry

Before uploading to XYZ Studio to make a map, a single data preparation step is required. XYZ Studio currently only allows data that includes geometry to be uploaded. What that means if that we can't upload data that just contains state or country names, we'll have to upload the actual polygon geometry data of these states.

What we'll need to do:

  • acquire open data of state polygon boundaries
  • merge the polygon boundaries data set to our marijuana legality data set
  • output a GeoJSON file

Luckily for us, there are plenty of websites online that we can find data sets of state boundaries. For this exercise, let's use the US States 20m file from Eric Celeste's website. Go ahead and download this file.

To join these the state boundaries file with the marijuana legal status file, we'll be using a simple node script.

This script will import a CSV and export a GeoJSON file. To read in the CSV, we'll use the handy Papaparse library.

Create a new project folder and run:

npm i papaparse

Then make a new file called merge.js that includes the following code:

const Papa = require('papaparse');
const fs = require('fs')

const marijuana  = Papa.parse(fs.readFileSync('./data.csv', 'utf8'), {
    header: true,
   dynamicTyping: true
const states = require('./gz_2010_us_040_00_20m.json');

states.features.forEach((feature, index) => {
   const { properties } = feature;

   //Marijuana data set doesn't have information on Puerto Rico, so remove it.
   if (properties.NAME === 'Puerto Rico') {
      states.features.splice(index, 1);
   } else {
      properties.STATUS = marijuana.find(m => m.state === properties.NAME).status;
      delete properties.GEO_ID;
      delete properties.LSAD;
      delete properties.CENSUSAREA;
      delete properties.STATE;

fs.writeFileSync('./output.geojson', JSON.stringify(states));

The above script merges the CSV data with the states polygon boundary to create a unified GeoJSON object.

To execute the script, run:

node merge.js

...and you should see a new file in your directory called output.geojson.

Upload to XYZ Studio

Now that we have a GeoJSON file with the state's geometries, we can upload it to XYZ Studio to make the map!

Navigate to HERE XYZ Studio and log in to your account.

Click on Data Hub in the top-level navigation menu and then Create new XYZ Space so we can begin uploading the data.

Drag and drop the file:


Make the map

Now that the data is uploaded to XYZ Studio, let's begin styling the data.

Navigate to Projects in the top-level navigation menu and then click Create new project.

Give the map a title and a description:


Next, click on + Add to add the marijuana data as a layer to XYZ Studio.

We can now start styling the polygons.

Conditional styling

We'll want to style the state polygons based off the marijuana legal status.

To do so, we'll use the conditional styling feature in XYZ Studio, where we can style the data based off a data's property.

Click on + Add new polygon style to create a new style group. We'll want to create 3 new style groups:

  • Fully legal. When STATUS Equals Fully legal
  • Medical only. When STATUS Equals Medical only
  • Illegal. When STATUS Equals Illegal

Once you've created those three style groups, you can play around with the styling to pick the colors that you prefer.

My final map looks like:



You've learned how to take a data set without geometry values and create a choropleth in XYZ Studio.

You can now publish and share your map easily by clicking the Publish Settings button.