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.
Using the Javascript API #
From the developer console #
If you want to do a quick test of the Javascript API, the fastest way to do it is to interact with it from the Developer Console. For example, in Chrome, you may open the Developer Tools, go to the Console and copy & paste the following snippet:
// 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;
}
});
After you do this, if you click & unclick a POI, you should see something like this in your Developer Console:
From a webpage #
First of all, you’ll need to integrate the Map Viewer in your webpage. One way to do this is by using an iframe, as explaned here. Then, on your code you may subscribe to the messages sent by the MapViewer using the window.addEventListener method. The following HTML code illustrates a full example:
<!DOCTYPE html>
<html>
<head>
<style>
body,
html {
padding: 0;
margin: 0;
}
</style>
</head>
<body>
<!-- Integrate the Map Viewer as an iframe in your webpage -->
<iframe
id="viewer"
style="width: 100%; height: 100vh"
src="http://map-viewer.situm.com/?email=YOUR_EMAIL@DOMAIN.COM&apikey=YOUR_APIKEY"
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>
Message structure and supported events #
When you receive postMessage from our API, you should pay attention to the following fields:
- type, which is always “message“. This is why you subscribe to the API using window.addEventListener(“message“, …)
- data, which is a JSON field that you need to parse. On the inside, it contains:
- type. Indicates the 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.
Please check the documentation to get an updated list to all the messages that you can send to the viewer (ACTIONS) and messages that you can receive from the viewer (EVENTS): https://developers.situm.com/sdk_documentation/map-viewer/
