Appearance

Distance Calculation ​

Compute indoor walking distances between a starting point and one or more destinations without drawing a visible route. Use this to sort search results by proximity, power "nearest facility" features, or display estimated walking times.

Prerequisites ​

  • A working map embed — complete Embed your first map first.
  • You need entity IDs for the start point and each destination. Discover them via the select event — see Map events.
  • calculateDistance requires the map to be inside a building (via applyBoost({floor, building}) followed by the floorChange event) and the indoor graph to be loaded. Pre-building calls resolve with message: "DataNotLoaded". We pad 4 s after floorChange to let the graph settle.

Steps ​

1. Navigate into a building ​

calculateDistance operates on indoor entities, so the map must first load the building graph. Register a floorChange listener, fire applyBoost({floor, building}), and do your distance query once the listener has been triggered.

javascript
mapsted.maps.init({
  element: document.getElementById("mapsted-map"),
  propertyId: 603,
  onload: function () {
    mapsted.maps.once("floorChange", function () {
      setTimeout(runDistanceQuery, 4000); // give the graph 4 s to load
    });
    mapsted.maps.applyBoost({ floor: 1355, building: 710 }); // CAW Student Centre · L1
  }
});

2. Build the request ​

calculateDistance takes a CalculationRequest with a start location and an array of destinations, each a LocationData union of {type, data}:

javascript
const query = {
  start: {
    type: "entity",
    data: { buildingId: 710, floorId: 1355, entityId: 302 }  // Information 192
  },
  destinations: [
    {
      type: "entity",
      data: { buildingId: 710, floorId: 1355, entityId: 3764 }  // Fairtrade Coffee
    },
    {
      type: "entity",
      data: { buildingId: 710, floorId: 1355, entityId: 22 }    // CAW building-level
    }
  ]
};

Alternative location types:

  • { type: "coordinate", data: { latitude, longitude, buildingId, floorId } } for arbitrary WGS84 points.
  • { type: "mapOverlay", data: { mapOverlayId } } for CMS-defined overlay regions.

3. Call calculateDistance ​

It returns a Promise<CalculationResult>. Check result.message — anything other than "Success" is a soft failure ("DataValidation", "DataNotLoaded", "Failed").

javascript
mapsted.maps.calculateDistance(query)
  .then(function (result) {
    console.log(result);
    /*
    {
      start: { type: "entity", data: { … } },
      destinations: [
        { destination: { type: "entity", data: { entityId: "3764", … } }, distance: "19 m" }, // pre-formatted distance string (locale-aware unit suffix)
        { destination: { type: "entity", data: { entityId: "22",   … } }, distance: "35 m" }
      ],
      message: "Success"
    }
    */
  });
Open in Sandbox ↗

4. Parse the distance value ​

distance is a pre-formatted string like "19 m" from the iframe wire (locale-aware unit suffix) — extract the number with a small regex helper before sorting or arithmetic.

javascript
function parseDistanceStr(s) {
  const m = /^(\d+(?:\.\d+)?)/.exec(String(s || ""));
  return m ? parseFloat(m[1]) : 0;
}

5. Sort by distance ​

javascript
mapsted.maps.calculateDistance(query)
  .then(function (result) {
    const rows = result.destinations
      .map(function (r) {
        return { id: r.destination.data.entityId, metres: parseDistanceStr(r.distance) };
      })
      .sort(function (a, b) { return a.metres - b.metres; });

    const nearest = rows[0];
    console.log("Nearest entity:", nearest.id, "—", nearest.metres.toFixed(1), "m");
  });

6. Convert metres to walking time ​

javascript
function metresToWalkTime(metres) {
  const seconds = metres / 1.4;  // comfortable indoor pace
  if (seconds < 60) return Math.round(seconds) + " sec";
  return Math.round(seconds / 60) + " min";
}

7. Handle errors ​

Wrap the call in a .catch for network / API-level errors, and check result.message for the API's own validation states.

javascript
mapsted.maps.calculateDistance(query)
  .then(function (result) {
    if (result.message !== "Success") {
      console.warn("calculateDistance returned:", result.message);
      return;
    }
    displayResults(result.destinations);
  })
  .catch(function (err) {
    console.error("Distance calculation failed:", err && err.message);
  });

Full example ​

javascript
mapsted.maps.init({
  element: document.getElementById("mapsted-map"),
  propertyId: 603,
  onload: function () {
    mapsted.maps.once("floorChange", function () {
      setTimeout(function () {
        const query = {
          start: { type: "entity", data: { buildingId: 710, floorId: 1355, entityId: 302 } },
          destinations: [
            { type: "entity", data: { buildingId: 710, floorId: 1355, entityId: 3764 } }
          ]
        };
        mapsted.maps.calculateDistance(query).then(function (result) {
          if (result.message !== "Success") return;
          result.destinations.forEach(function (r) {
            console.log("Entity " + r.destination.data.entityId + ": " + r.distance);
          });
        });
      }, 4000);
    });
    mapsted.maps.applyBoost({ floor: 1355, building: 710 });
  }
});
Open in Sandbox ↗

Expected output ​

After the map enters CAW Student Centre L1 and the indoor graph loads, the console prints one line per destination sorted from shortest to longest walking distance. For a 302 → 3764 query (Information 192 → Fairtrade Coffee, same floor) the API returns approximately 19 m, which at 1.4 m/s = ~14 seconds. Distances reflect the actual indoor path — not straight-line — accounting for walls, corridors, and multi-floor transitions.

V2/V3 event API deprecated

mapsted.maps.addEventListener() and mapsted.maps.removeEventListener() are deprecated V2/V3 compatibility shims. They emit a console.warn and throw MAPSTED-1093 in strict mode. Use the emitter API: on(), off(), and once() as shown throughout this page.

Next steps ​