Measure MapHelp
Open Measure Map

iFrame API

Show one of your projects as a live map on your own website, in the units, map style and theme that suit your site.

The iFrame API puts a project's map on your own web page. Visitors see the satellite map with your measurements and can move around it, without an account and without leaving your site. You choose the project, the units, the map style and the colour theme.

Before you start#

  • A live API key with Embedded maps access. See API keys.
  • A project that visitors may see. Set its access level to View only or Public. A Private project does not open for visitors without an account. See which projects can be embedded.
  • Optionally, website restrictions on the key, so the embed only works on your own sites. See API keys.

Build the embed code#

Developer > Embed a map builds the code for you with your live key: pick the project, choose the theme, units, map type and size, check the Live preview, and copy the Embed code. If the project is private, the section says so and offers Make it view only. See get the embed code for each step.

Embed a map with a project picked and the live preview

The code carries your key, so it keeps working until you replace the key. The section warns you when the key can do more than Embedded maps, since anyone can read it in your page's source, and when the key has no website restrictions. Only the Live preview uses a short-lived token. See key or token.

The embed address#

An embed is an <iframe> whose address starts with https://app.measuremaponline.com/iframe_api, followed by these parameters:

Parameter Needed Values
pid required The project's identifier: the part after /p/ in the project's address in the app.
key key or token Your API key.
token key or token A token from your server (see below).
ms optional Units: metric or imperial. Without it, visitors in the United States see imperial units and everyone else metric.
maptype optional satellite (the default), map, hybrid or terrain.
theme optional auto (the default: follows the visitor's own system setting), light or dark.

A minimal example#

<iframe src="https://app.measuremaponline.com/iframe_api?pid=YOUR_PROJECT_ID&key=YOUR_API_KEY&maptype=satellite&theme=auto"
  title="YOUR_PROJECT_NAME" width="500" height="500" style="border:0" allow="fullscreen"></iframe>

Replace YOUR_PROJECT_ID, YOUR_API_KEY and YOUR_PROJECT_NAME (screen readers read the title out), and set the width and height to fit your page.

The embed code with its copy button

Key or token#

With key, as in the code the Embed a map section gives you, the embed keeps working as long as the key does, on the websites its restrictions allow. Your key is then visible in your page's source, so:

  • use a key with Embedded maps access only;
  • restrict it to your own websites;
  • when you replace the key, update your pages within the 24 hours the old key keeps working.

With token, the key stays on your server. This suits embeds your own server writes into the page for each visit: before showing the page, it asks the REST API for a token and puts it in the iframe's address:

  • POST https://api.measuremaponline.com/api/v2/auth/iframe/token, with your key in the Authorization header, returns a token that works for 60 minutes;
  • POST https://api.measuremaponline.com/api/v2/auth/token does the same and accepts a duration in seconds, up to 24 hours. Its answer says when the token expires.

Your account can get up to 600 tokens an hour. Use a live key: embeds show live projects only, so a token made with a sandbox key does not open a map. See the API reference.

What visitors can do#

Visitors can pan and zoom the map and read the measurements of your shapes. They cannot change anything: editing is switched off inside an embed, whatever the project's access level. The only exception is an Open Guest project on the Open Guest plan, where visitors measure for themselves.

When the map does not appear#

Check, in order:

  • The address has a token that has expired. Tokens last 60 minutes unless your server asked for longer. Copy the code again from Embed a map, which uses your key, or have your server get a fresh token for each visit (see above).
  • The project is private. Set it to View only or Public, or press Make it view only in Embed a map.
  • The website is not allowed. If the key has website restrictions, 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.
  • The key was replaced. An old key stops 24 hours after a new one is created, or at once if it was revoked.
  • The key is a sandbox key. Embeds work with live keys and live projects only.
  • The subscription is not active, or API access has been suspended: the API keys section says so.

Still need help?

Write to our support team and tell us what you were trying to do. Screenshots help.

Email support