The Situm Map Viewer offers a Javascript API so you can interact programmatically with it. This API is based on postMessage(), which is a method in JavaScript that allows communication between two windows, such as an iframe and its parent window, or between two separate browser windows.
The Situm Map Viewer can both receive actions (with which you can modify the Viewer’s behaviour) and emit events (with which you may be aware of the Viewer state or the actions the user performs in it). To know more about these, please visit the Map Viewer’s API specification docs.
Sending actions to the viewer #
The first you might want to do is to send actions to the map viewer: setting the camera view, selecting a POI, selecting a building / floor, selecting a POI category, etc. To do so, you’ll need to send a message through the postMessage API with a JSON object that contains a:
- type: string identifying the action to be performed.
- payload: JSON object with the relevant data.
Here’s an example on how to select a POI from the Browser Javascript console (e.g. in Chrome, you may open the Developer Tools, go to the Console and copy & paste the following snippet) and within a webpage. For more details about the actions and their definition, please check the API specification.
window.postMessage({
"type": "cartography.select_poi",
"payload": {
"identifier": 671388
}
})
<!DOCTYPE html>
<html>
<head>
<style>
body,
html {
padding: 0;
margin: 0;
}
</style>
</head>
<body>
<!-- Integrate the Map Viewer as an iframe in your webpage -->
<!--Make sure to point to your viewer ID (e.g. https://map-viewer.situm.com/id/YOUR_ID) or use a valid APIKEY (e.g. https://map-viewer.situm.com/?apikey=YOUR_APIKEY)-->
<iframe
id="viewer"
style="width: 100%; height: 100vh"
src="https://map-viewer.situm.com/"
frameborder="0"
></iframe>
<script>
document.addEventListener("DOMContentLoaded", function (event) {
// Send message to iframe
let frame = document.getElementById("viewer");
frame = frame ? frame.contentWindow : null;
setInterval(() => {
frame.postMessage(
JSON.stringify({
type: "cartography.select_poi", // Desired action
payload: { id: 1234 }, // Substitute with your desired POI ID
}),
"*"
);
}, 2000);
});
</script>
</body>
</html>
This is the result in a browser:
Receiving events from the viewer #
Similarly, the Map Viewer allows you to receive events: when the user selects / deselects a POI or other cartography elements, when the user requests directions, etc. To subscribe to the Map Viewer events, you’ll need to add an event listener by calling window.addEventListener(type, listener). This function receives two parameters:
- type: in our case it will always be “message”.
- listener: a function where you’ll receive the response.
Then, you’ll need to parse the JSON data object you’ll receive, which will contain the following fields:
- type: type of event issued by the Map Viewer: cartography.poi_selected, cartography.poi_deselected, etc.
- payload: additional data, such as the POI Identifier in case of a cartography.poi_selected event.
Here’s an example on how to receive POI selection / deselection events from the Browser Javascript console (e.g. in Chrome, you may open the Developer Tools, go to the Console and copy & paste the following snippet) and within a webpage. For more details about the actions and their definition, please check the API specification.
// You may subscribe to the API messages ...
window.addEventListener("message", (e) => {
var data = e.data;
const parsedData = JSON.parse(data.replaceAll("'", '"'));
// ... and operate on the received data, which contains "type" and a "payload" fields
switch (parsedData.type) {
//In this example, we just care for POI (de)selected events
case "cartography.poi_selected":
case "cartography.poi_deselected":
console.log("Known message received. Type: ", parsedData.type, " Payload: ", parsedData.payload);
break;
// ... but the API issues more messages!!
default:
console.info("Unknown message received: ", parsedData);
break;
}
});
<!DOCTYPE html>
<html>
<head>
<style>
body,
html {
padding: 0;
margin: 0;
}
</style>
</head>
<body>
<!-- Integrate the Map Viewer as an iframe in your webpage -->
<!--Make sure to point to your viewer ID (e.g. https://map-viewer.situm.com/id/YOUR_ID) or use a valid APIKEY (e.g. https://map-viewer.situm.com/?apikey=YOUR_APIKEY)-->
<iframe
id="viewer"
style="width: 100%; height: 100vh"
src="http://map-viewer.situm.com/"
frameborder="0"
></iframe>
<script>
//After the DOM loads...
document.addEventListener("DOMContentLoaded", function (event) {
// ... you may subscribe to the API messages ...
window.addEventListener("message", (e) => {
var data = e.data;
const parsedData = JSON.parse(data.replaceAll("'", '"'));
// ... and operate on the received data, which contains "type" and a "payload" fields
switch (parsedData.type) {
//In this example, we just care for POI (de)selected events
case "cartography.poi_selected":
case "cartography.poi_deselected":
console.log("Known message received. Type: ", parsedData.type, " Payload: ", parsedData.payload);
break;
// ... but the API issues more messages!!
default:
console.info("Unknown message received: ", parsedData);
break;
}
});
});
</script>
</body>
</html>
Here’s the result:
