05 – Javascript API (experimental)

Warning!!! This is an experimental feature and therefore may change a lot in the future (including breaking changes).

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.

The following table documents the currently implemented events with their data.type and data.payload:

EventDescriptiondata.typedata.payload
POI selectedUser has selected a POIcartography.poi_selected{id: POI_ID}
where POI_ID is the POI identifier (number)
POI deselectedUser has deselected a previously selected POIcartography.poi_deselected{id: POI_ID}
where POI_ID is the POI identifier (number)
Floor selectedUser has changed the view to a certain floorcartography.floor_selected{id: FLOOR_ID}
where FLOOR_ID is the floor identifier (number)
Building selectedUser has changed the view to a certain buildingcartography.building_selected{id: BUILDING_ID}
where BUILDING_ID is the building identifier (number)

Subscribe to our newsletter

BASIC INFORMATION ON DATA PROTECTION

Data controller: SITUM TECHNOLOGIES, S.L.
Contact: Data controller: situm@situm.es
Responsible for protection: dpo@situm.es
Purpose and legal basis: To manage the sending of SITUM newsletters only with consent.
Legitimation: Express consent of the interested party.
Recipients: The data will not be passed on to third parties with the exception of legal obligations.
Retention period: As long as the interested party remains subscribed to the newsletter (a link to unsubscribe will be available in each newsletter sent by Situm).
Rights: The interested party may at any time revoke their consent, as well as exercise their rights of opposition, access, conservation, rectification, limitation, deletion of data and not be subject to a decision based only on automated data processing, by writing to SITUM at the addresses indicated.
Additional Information: You can consult additional and detailed information on Data Protection in our privacy policy.

Please, download your copy here

Thank you for downloading our whitepaper. Please do not hesitate to contact us if you would like to know more about how our solutions can help your business. Download whitepaper


Close window