Creating a Locator Map

📘
You need an API Access Token
Everything you need to follow this tutorial is a Datawrapper account and an API Access Token. Both are available for free. You can create an API Access Token with the click of a button in your Datawrapper settings. Learn how to do so in this article.

Besides symbol maps and choropleth maps, you can create locator maps in Datawrapper, using the same API endpoints that you use for charts. Locator maps are a great choice if you want to show where something is located or has happened. They don't require you to select a basemap: all you need is to decide on where to place markers and how to style them.

Creating a locator map

Let's start with a short POST request to create your map. To do so, define the visualization type in the API request. (Defining the title is not necessary, but it can't hurt.)

curl --request POST \
  --url https://api.datawrapper.de/v3/charts \
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  --header 'content-type: application/json' \
  --data '{ "title": "My locator map", "type": "locator-map" }'

This will give you back a response with your id. In our case, that's U2Dba. You should remember your map ID, because you will need it for many of your following API requests. For example, if your chart id was th4ns, you'll need to insert that in the examples below every time you'll see the placeholder <ID> – otherwise, your requests won't work.

Updating your map settings

Locator maps consist of two types of settings: markers, which contain the points, lines and areas you want to display on your map, and metadata, which controls settings like the view of the map and which layers are visible.

It makes sense to start by updating the metadata to ensure that your map shows the cut of the world that you want to be visible. Below is a minimal example of locator map metadata settings. This might look like a lot, but don't worry: you can leave most of these at their default settings, and we'll cover what exactly they control later on.

curl --request PATCH \
  --url https://api.datawrapper.de/v3/charts/<ID> \
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  --header 'content-type: application/json' \
  --data '{ 
    "metadata": {
  			"data": {
      			"json": true
        },
        "visualize": {          
            "view": {
                "center": [ -0.106, 51.523 ],
                "zoom": 8,
                "fit": {
                    "top": [0.176, 53.408],
                    "right": [1.368, 51.779],
                    "bottom": [0.241, 51.1425],
                    "left": [-0.920, 51.754]
                },
                "height": 120,
                "pitch": 0,
                "bearing": 0
            },
            
            "style": "dw-light",

            "defaultMapSize": 500,
            
            "visibility": {
                "boundary_country": true,
                "boundary_state": true,
                "building": true,
                "green": true,
                "mountains": true,
                "roads": true,
                "urban": true,
                "water": true,
                "building3d": false
            },

            "mapLabel": true,
            "scale": false,
            "compass": false,

            "miniMap": {
                "enabled": false,
                "bounds": []
            },
            "key": {
                "enabled": false,
                "title": "",
                "items": []
            }
        }
     }
  }'

The most important thing in your map's metadata setting is the view object. It controls which part of the world your map will show, and at which zoom level. Specifically, it will allow you to define the following properties:

Property	Purpose	Example value
`view.center`	The `center` property contains a coordinate pair in the form of a lon/lat array that defines thecenter point of the map.	`[ -0.792, 51.007 ]`
`view.zoom`	The `zoom` property contains the zoom level of the map, on a scale from `0` (the whole world) to `15`).	`8`
`view.fit`	The `fit` property contains 4 coordinate pairs - `top`, `right`, `bottom` and `left`. They make up the 4 outer points of the view container. (see image below) Why is there a `fit` property, when the `center` and `zoom` together already impact the view? The reason is that for mobile responsiveness, you might want to ensure that you always show a certain view, regardless of the map size. Setting `fit` will ensure that the defined view is always visible, even if it means the zoom level is slightly reduced.	`"fit": { "top": [0.176, 53.408], "right": [1.368, 51.779], "bottom": [0.241, 51.1425], "left": [-0.920, 51.754] }`
`view.height`	The `height` property contains the desired aspect ratio of the map in %. That means providing `100` as the `height` value will result in a quadratic map, and e.g. `50` would result in a 'landscape' view.	`100`
`view.bearing`	The `bearing` property controls the rotation of the map, with `0` resulting in a north-oriented map.	`0`
`view.tilt`	The `tilt` property allows you to tilt the map by a specified degree between `0` and `60`.	`0`

Some other important settings to control your map are the following:

Property	Purpose	Example value
`style`	The color scheme of your map. Valid options for the default Datawrapper theme are `dw-light`, `dw-earth`, `dw-white` and `dw-white-invert`, which correspond to the Map styles available in step 2 of the locator map editor.	`dw-light`
`mapLabel`	This property controls whether you want to display automatically generated labels on your map.	`true`
`compass`	This property controls whether you want to display a compass for orientation in the corner of your map.	`false`
`scale`	This property controls whether you want to display a scale legend in the corner of your map.	`false`
`visibility`	The `visibility` property contains an object that specifies which layers are displayed on your map. Each layer can be enabled or disabled as a boolean flag: `boundary_country` `boundary_state` `building` `green` `mountains` `roads` `urban` `water` `building3d` These layers correspond to the checkbox options in step 2 in the locator map editor.	`{ boundary_country: true, boundary_state: true, building: true, green: true, mountains: true, roads: true, urban: true, water: true, building3d: false }`
`defaultMapSize`	This option controls the default size at which the locator map will be displayed when opened in the Datawrapper editor. It does not have any impact on the display of your published map.	`500`

Previewing your map

You can preview your map by logging into your Datawrapper account and opening it. This is how our map looks so far:

We can see our defined map view, but not much else so far! In order for our map to become useful, we need to add markers. To learn more about how to add markers to your map, have a look at these articles:

📘You need an API Access Token

Creating a locator map

Updating your map settings

Previewing your map

📘
You need an API Access Token