Embedding a Mapworks Map

Level of Experience Basic
Requirements Mapworks Organisation Admin login and basic JavaScript knowledge
Time Required 15 min
Source Code https://github.com/mapworksio/embedded-map


The strength of Mapworks is the ability for you to easily integrate a feature rich vector map into your current web applications via the map APIs.

This tutorial will walk through how to embed your map and will form the basis for all future tutorials. 

Embeding Using iFrame

The easiest way to embed a map into your application is to use an iFrame via the Mapworks portal as described here. However, there are two limitations to this:

  1. This requires your map and all layers to be public, which means it will be visible to the whole world and discoverable through mapworks
  2. Javascript API access to the iFrame can pose challenges 

Embedding Using HTML

If you want to do any API level interaction with the map, we recommend that you add the map object directly into your webpage via JavaScript. Below is a typical example of how you would embed a Mapworks map into a HTML page. Feel free to clone this from Github at https://github.com/mapworksio/embedded-map

<!doctype html>
<html lang="en">
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
   <title>A Mapping Application</title>
   <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1.0, user-scalable=no">
   <link rel="stylesheet" href="https://api.mapworks.io/studio/latest/css/studio-core.css">
   <script src="https://api.mapworks.io/studio/latest/js/studio-core.js" type="text/javascript"></script>
   <style type="text/css">
      body, html {
         width: 100%;
         height: 100%;
         margin: 0;
         padding: 0;
         overflow: hidden;
      #mapworks-map {
         width: 100%;
         height: 100%;
   <div id="mapworks-map"></div>
   <script type="text/javascript">
      var map = new Studio.core.Map("#mapworks-map", {
         // Your API key.
         // 1. Login to the Mapworks application (https://app.mapworks.io).
         // 2. Click on "Settings" (the cog icon).
         // 3. Click "API Keys".
         // 4. Click "Create API Key".
         // 5. Enter an API key name.
         // 6. Search and add content that you want to API to have access to.
         // 7. Click the "Create" button.
         // 8. Copy and replace <your api key> with your api key.
         apiKey: "<your api key>",
         // The map identifier of the map that was added to the API key.
         map: "<map id>",
         // Enable or disable the Navigation Control UI.
         navigationControl: true,
         // Enable or disable the Scale Control UI.
         scaleControl: true,
         // Enable or disable the Tooltip Control.
         tooltipControl: true,
         // Enable or disable the Zoom Control UI.
         zoomControl: true
      }).load(function() { // Load the map
      // Call when the map has finished
      map.once('ready', function() {

This does a number of things

  1. It downloads the required JavaScript and CSS files
  2. It defines a div where where the map is going to be placed called "mapworks-map"
  3. It creates the map object with a given API key and Map ID
  4. It does some inital configuration of which default tools are available

Map Life Cycle

The Mapworks map goes through the following life cycle

  1. Map object creation - This is when new Studio.core.Map() is called and begins the setup of the map
  2. Map loaded - This is when the map object has been loaded into the DOM
  3. UI widgets loaded - After the map has been added to the DOM, the Studio widgets are loaded in and set up
  4. Map ready - This is when the layers have finished loading and the map API is ready to be used
  5. Map destroyed - This occurs either when the user navigates away from the page or when map.destroy() is called

Getting your Map ID

In order to embed you map, you need two things. The first is that you need the map ID that you want to display. 

This is found by opening up your map through Mapworks and viewing the map info. You'll find the ID under "Unique Reference"

Generating an API Key

The second thing you'll need is an API key. For this you'll need to log into Mapworks as the admin user of your organisation.

At the top right. Click on the "Settings" button

Click on the "API Keys" tab on the left. That should give you a list of API keys you currently have. 

Click "Create API Key"

Set the name of your API key and what maps or layers to be associated with the API key. Note that if your map includes private layers, you will need to include these layers as well. 

Specify if the application can edit or only view the map using the API key. If you wish, you can also specify the allowed referrers for this API key

Once you're done, Click create and copy the API key into your application

Note that you don't need your map / layer to be public in order for it to be accessible through an API key. 

This now provides you a map that you can directly interact with.

Next: Adding a Layers Panel Widget