Open Guest · Measure Map Online API

Let each visitor to your website measure in a project of their own, with their details filled in, billed per guest project.

On the Open Guest plan, visitors to your website measure their own property in a project of their own, inside your account. You receive their details and their measurements, and pay per guest project.

There are two ways to start guest projects:

The guest link, with no code: a link from the Developer page's Guest link section, for a button on your site.
Your server, with the API: your page knows who the visitor is (from your quote form, say) and their project starts with their details filled in. This guide covers that way.

How it works#

The visitor fills in your form and presses a button.
Your server gets a token with your live key: Create an access token.
Your server redirects the visitor to the app's guest start page with the token and their details.
The app creates an Open Guest project in your account and opens it. The visitor measures, and can ask you for an estimate.
You hear about it by email and, if you set one up, by webhook: guest.project.created, then guest.measurement.completed when they ask for the estimate.

The server route#

Node.js (Express)

// Your API key stays on this server, in an environment variable.
app.get('/start-measuring', async (req, res) => {
  const reply = await fetch('https://api.measuremaponline.com/api/v1/auth/token', {
    method: 'POST',
    headers: {'Authorization': process.env.MMO_API_KEY, 'Content-Type': 'application/json'},
    body: JSON.stringify({duration: 900}), // 15 minutes is plenty to load the page
  });
  if (!reply.ok) {
    return res.sendStatus(502);
  }
  const {token} = await reply.json();
  const params = new URLSearchParams({
    token,
    name: String(req.query.address || 'New measurement'), // the project's name in your account
    guest_name: String(req.query.name || ''),
    guest_email: String(req.query.email || ''),
    guest_phone: String(req.query.phone || ''),
    // folder_id: 'FOLDER_ID',  // optional: a folder of yours to file guest projects in
  });
  res.redirect('https://app.measuremaponline.com/app/projects/guest/new?' + params);
});

Python (Flask)

import os
import requests
from flask import Flask, redirect, request, abort
from urllib.parse import urlencode

app = Flask(__name__)

@app.get("/start-measuring")
def start_measuring():
    reply = requests.post(
        "https://api.measuremaponline.com/api/v1/auth/token",
        headers={"Authorization": os.environ["MMO_API_KEY"]},
        json={"duration": 900},
        timeout=10,
    )
    if not reply.ok:
        abort(502)
    params = {
        "token": reply.json()["token"],
        "name": request.args.get("address", "New measurement"),
        "guest_name": request.args.get("name", ""),
        "guest_email": request.args.get("email", ""),
        "guest_phone": request.args.get("phone", ""),
    }
    return redirect("https://app.measuremaponline.com/app/projects/guest/new?" + urlencode(params))

And on your page, the button opens that route:

JavaScript

function startMeasuring(form) {
  const params = new URLSearchParams({address: form.address.value, name: form.name.value, email: form.email.value});
  window.open('/start-measuring?' + params.toString(), '_blank', 'noopener');
}

The guest start page#

https://app.measuremaponline.com/app/projects/guest/new takes these query parameters:

Parameter	Needed	What it is
`token`	required	A token from Create an access token, made with a live key.
`name`	optional	The project's name in your account.
`description`	optional	Any text you want to find the project by later.
`guest_name`	optional	The visitor's name, shown to them and in the email you receive.
`guest_email`	optional	The visitor's email address. You are only told about the project when it is known.
`guest_phone`	optional	The visitor's phone number.
`folder_id`	optional	One of your folders, to file the project in.

Encode every value (URLSearchParams or urlencode do it): a name like "Smith & Sons" must arrive whole.

Budget and billing#

Each guest project is counted when it is created and billed with your subscription. Projects made with a sandbox key are never counted or billed.
Set a warning and a limit for the billing period on the Developer page. At the limit, new guest projects are refused: the visitor sees that measuring is not available, and the API answers 402 budget_limit_reached. Webhooks budget.warning_reached and budget.limit_reached tell your server.
Guest projects are only started while the subscription is active.

From your server only#

To create guest projects without sending a visitor, for example to prepare one before a phone call, use Create a project with access_level: "open_guest" and the guest's details in guest. It is counted and billed the same way.