Embedding projects

An embed puts a project's map on your web page in an <iframe>. Visitors see the satellite map with your measurements and can move around it, without an account and without leaving your site.

Before you start#

• A live key with Embed access. Sandbox projects cannot be embedded.
• A project visitors may see: its access level must be View only or Public. A Private project does not open for visitors. Projects made with Create a project for a person are view only from the start.
• Website restrictions on the key (recommended), so the map only opens on your own sites. See Website restrictions.

The Developer page's Embed a map section builds the code for you, with a live preview.

The embed address#

https://app.measuremaponline.com/iframe_api?pid=PROJECT_ID&key=YOUR_API_KEY

<iframe
  src="https://app.measuremaponline.com/iframe_api?pid=PROJECT_ID&key=YOUR_API_KEY&maptype=satellite&theme=auto"
  title="14 Harbour Road" width="600" height="450" style="border:0" allow="fullscreen"></iframe>

Give the iframe a title: screen readers read it out.

Key or token#

With key= the embed works as long as the key does, and your key is visible in the page's source. Use a key with Embed access only, restrict it to your websites, and when you replace the key, update your pages within the 24 hours the old one keeps working.

With token= the key stays on your server. Before showing the page, your server asks for a token and writes it into the iframe's address:

// Express route that renders the page with a fresh embed token.
app.get('/our-work/:projectId', async (req, res) => {
  const reply = await fetch('https://api.measuremaponline.com/api/v1/auth/iframe/token', {
    method: 'POST',
    headers: {Authorization: process.env.MMO_API_KEY},
  });
  if (!reply.ok) {
    return res.sendStatus(502);
  }
  const {token} = await reply.json();
  const src = new URL('https://app.measuremaponline.com/iframe_api');
  src.searchParams.set('pid', req.params.projectId);
  src.searchParams.set('token', token);
  res.render('our-work', {iframeSrc: src.toString()});
});

import os
import requests
from urllib.parse import urlencode

def embed_src(project_id: str) -> str:
    reply = requests.post(
        "https://api.measuremaponline.com/api/v1/auth/iframe/token",
        headers={"Authorization": os.environ["MMO_API_KEY"]},
        timeout=10,
    )
    reply.raise_for_status()
    token = reply.json()["token"]
    return "https://app.measuremaponline.com/iframe_api?" + urlencode({"pid": project_id, "token": token})

<?php
$ch = curl_init('https://api.measuremaponline.com/api/v1/auth/iframe/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: ' . getenv('MMO_API_KEY')],
]);
$token = json_decode(curl_exec($ch), true)['token'];
curl_close($ch);
$src = 'https://app.measuremaponline.com/iframe_api?' . http_build_query(['pid' => $projectId, 'token' => $token]);

• Create an embed token gives a token that works for 60 minutes.
• Create an access token takes a duration in seconds, up to 24 hours, so one token can serve many page views.

Your account can mint up to 600 tokens an hour: see Rate limits.

What visitors can do#

Visitors can pan and zoom and read the measurements. They cannot change anything: editing is switched off inside an embed, whatever the project's access level. The exception is an Open Guest project, where the visitor measures for themselves.

When the map does not appear#

Check, in order:

1. The token has expired. Tokens from Create an embed token last 60 minutes; have your server get a fresh one for each page view, or a longer one.
2. The project is private. Set it to View only or Public in the app.
3. The website is not allowed. With website restrictions on the key, the page showing the embed must be on one of them. Some browsers and sites hide which page an embed is on; with restrictions set, such an embed is refused.
4. The key was replaced more than 24 hours ago, or revoked.
5. The key or token is a sandbox one. Embeds open live projects only.
6. The subscription is not active, or API access is suspended.