'easyGuide maps engine' logo easyGuide maps engine - API Documentation

News

New in V1.0.0: New popup() option "anchor"; new focus() option "rotation", new get/set option "flood", reset() sets now initial rotation, font support for text features, larger start/end/line of sight icon support, text labels with fixed roation are now for any roation bottom down, removed fixed zoom step requirement, fixed line-of-sight bug, upgraded to ol 5.3.0

Introduction

"easyGuide maps engine" is a lightweight JavaScript library that allows external developers to easily add an interactive map to their web application with just a few lines of code. "EasyGuide maps" are in particular geared to allow navigation and orientation within buildings. Native app developers (Kotlin/Java, Swift/Objective-C, etc.) can also take advantage of this library via the common WebView (Android) / WKWebView (iOS) components using the two-way JavaScript Interface in Android and iOS. For "easyGuide maps engine" to work an internet connection is required. The one-time heavy-lifting setup to add a particular building is done by the service provider (= us) and hidden from the service consumer (= you).

The following documentation describes the Open API of the "easyGuide maps engine" in detail allowing developers to easily integrate it in their own applications. Follow this link for a high-level overview of the overall functionalities.

Example

Loading...
# Return (async) Method Test Documentation
1 = EasyGuideMapsEngine.toString();
2 = EasyGuideMapsEngine.refresh();
3 = EasyGuideMapsEngine.reset();
4 = EasyGuideMapsEngine.screenshot();
5 = EasyGuideMapsEngine.retrieve( , { visible-only: });
6 = EasyGuideMapsEngine.retrieveClosestElementsByCoordinates([ , ], ));
7 = EasyGuideMapsEngine.get( );
8 = EasyGuideMapsEngine.set( , );
9 = EasyGuideMapsEngine.route([ , ], { "accessible": });
10 = EasyGuideMapsEngine.focus( , { , , });
11 = EasyGuideMapsEngine.highlight([ ], , , );
12 = EasyGuideMapsEngine.popup( , , { close-button: , auto-pan: , anchor: });
The events EVENT_USER_INTERACTION, EVENT_FUNCTION_RETURN are not displayed here. Hava a look at the browser console (= F12) to see the history of all events.
...

Playground

Play directly with the easyGuide maps engine - API using our playground.

Versioning

The "easyGuide maps engine" uses Semantic Versioning. The version number MAJOR.MINOR.PATCH changes as follows:

The method EasyGuideMapsEngine.toString() returns the current name and version number of the "easyGuide maps engine" library.

Setup

  1. Include the easyGuide maps engine JavaScript file in the header and add a <div>-container with an id to the body where you want the map to be displayed.

    <!DOCTYPE html>
    <html>
      <head>
        <title>easyGuide maps engine - Example</title>
        <script src="https://engine.easy-guide.com/EasyGuideMapsEngine_V0.3.8.min.js"></script>
        <script src="MyScript.js"></script>
      </head>
      <body>
        <div id="divMap" style="width:400px;height:300px;background-color:#C0C0C0;">Loading...</div>
      </body>
    </html>
  2. Create a new EasyGuideMapsEngine instance in your JavaScript code after the DOM content has been loaded.

    Options:

    1. debug: boolean (optional): Enable or disable debug mode. In debug mode the ids of elements are displayed on the map and additional output in printed to the browser console. Default value is false.
    2. project: number: The six-digit unique project id defined by the service provider.
    3. key: string: The individual project API license key - use "demo" for testing purposes.
    4. container: string: The id of the <div> element, where you want the map to be displayed. Any other content in the <div> element will be removed.
    window.document.addEventListener("DOMContentLoaded", function() {
    
        var oEasyGuideMapsEngineOptions = {
            "debug": false,
            "project": 100102,
            "key": "demo",
            "container": "divMap"
        };
        var oEasyGuideMapsEngine = new EasyGuideMapsEngine(oEasyGuideMapsEngineOptions);
    
    });
The TypeScript declaration file can be downloaded at https://engine.easy-guide.com/EasyGuideMapsEngine_V1.0.0.d.ts

Controls

  1. You can enable/disable specific build-in controls via the controls: object parameter of the options object literal.

    window.document.addEventListener("DOMContentLoaded", function() {
    
        var oEasyGuideMapsEngineOptions = {
            "debug": false,
            "project": 100102,
            "key": "demo",
            "container": "divMap",
            "controls": {
                "attribution": true,
                "zoom": true,
                "rotation": true,
                "scaleline": true, 
                "layer": true,
                "route": true
              }
        };
        var oEasyGuideMapsEngine = new EasyGuideMapsEngine(oEasyGuideMapsEngineOptions);
    
    });
  2. Each control can be enabled/disabled individually.

    # control value description
    1 attribution bEnable: boolean Displays a little 'i'nfo-icon with copyright information. If disable the information is permanently displayed in the lower right corner.
    2 zoom bEnable: boolean Displays a zoom in/out control.
    3 rotation bEnable: boolean Displays a rotation/heading indicator control. Activating the control will align the map to the north.
    4 scaleline bEnable: boolean Displays a true-to-scale distance indicator control.
    5 layer bEnable: boolean Displays a layer control allowing the user to switch between floors.
    6 route bEnable: boolean Displays a route control with a step-by-step navigation for each route section. When enabled the control is only visible if a route is currently displayed on the map.

Events

  1. You can register a function to listen to events triggered by the map via the callback: function parameter of the options object literal.

    window.document.addEventListener("DOMContentLoaded", function() {
    
        var oEasyGuideMapsEngineOptions = {
            "debug": false,
            "project": 100102,
            "key": "demo",
            "container": "divMap",
            "controls": {"attribution": true, "zoom": true, "rotation": true, "scaleline": true, "layer": true, "route": true},
            "callback": onMapEvent
        };
        var oEasyGuideMapsEngine = new EasyGuideMapsEngine(oEasyGuideMapsEngineOptions);
    
    });
  2. The event listener function is passed an event with an id: string property to identify the type of event and a variant number of properties depending on the event type.

    # id trigger properties
    1 EasyGuideMapsEngine.EVENT_LOADED Fired when the instance has loaded info: string
    2 EasyGuideMapsEngine.EVENT_LAYER_CHANGED Fired when the user or an internal engine event triggered a layer change layer: string, formerLayer: string
    3 EasyGuideMapsEngine.EVENT_ZOOM_CHANGED Fired when the user or an engine event triggered a zoom change zoom: number, minZoom: number, maxZoom: number
    4 EasyGuideMapsEngine.EVENT_ROTATION_CHANGED Fired when the user or an engine event triggered a rotation change rotation: number
    5 EasyGuideMapsEngine.EVENT_POPUP_ELEMENT_SELECTED Fired when a html-element with an id-attribute is selected inside the popup element: string
    6 EasyGuideMapsEngine.EVENT_TARGET_SELECTED Fired when the user has selected an element (highlighter, point, icon or text) on the map type: string, target: string, coordinates.longitude: number, coordinates.latitude: number
    7 EasyGuideMapsEngine.EVENT_USER_INTERACTION Fired when the user interacts in any way with the map type: string ("mousedown", "mouseup", "mousewheel", "touchstart", "touchend", "click"), layer: string, clientX: number, clientY: number, coordinates.longitude: number, coordinates.latitude: number
    8 EasyGuideMapsEngine.EVENT_FLOOD_COMPLETED Fired when a flood animation has completed -
    9 EasyGuideMapsEngine.EVENT_FUNCTION_RETURN Fired when the return value of a previously executed EasyGuideMapsEngine function call is returned asynchronous functionName: string, functionArguments: any[], returnValue: any
    function onMapEvent (oEvent) {
    
        switch (oEvent.id) {
            case EasyGuideMapsEngine.EVENT_LOADED:
                console.log(oEvent.info + " loaded");
                break;
            case EasyGuideMapsEngine.EVENT_LAYER_CHANGED:
                console.log("Layer changed from \"" + oEvent.formerLayer + "\" to \"" + oEvent.layer + "\"");
                break;
            case EasyGuideMapsEngine.EVENT_ZOOM_CHANGED:
                console.log("Zoom changed to " + oEvent.zoom + " (min/max = " + oEvent.minZoom + "/" + oEvent.maxZoom + ")");
                break;
            case EasyGuideMapsEngine.EVENT_ROTATION_CHANGED:
                console.log("Rotation changed to " + oEvent.rotation);
                break;
            case EasyGuideMapsEngine.EVENT_POPUP_ELEMENT_SELECTED:
                console.log("Popup element \"" + oEvent.element + "\" selected.");
                break;
            case EasyGuideMapsEngine.EVENT_TARGET_SELECTED:
                console.log(oEvent.type + " \"" + oEvent.target + " + " + oEvent.modifier + "\" selected" + " (longitude: " + oEvent.coordinates.longitude + ", latitude: " + oEvent.coordinates.latitude + ")");
                break;
            case EasyGuideMapsEngine.EVENT_USER_INTERACTION:
                console.log("User " + oEvent.type + "-ed on layer " + oEvent.layer + " at pixel x/y = " + oEvent.clientX + "/" + oEvent.clientY + " and coordinates longitude/latitude = " + oEvent.coordinates.longitude + "/" + oEvent.coordinates.latitude);
                break;
            case EasyGuideMapsEngine.EVENT_FLOOD_COMPLETED:
                console.log("Flood animation has completed");
                break;            
            case EasyGuideMapsEngine.EVENT_FUNCTION_RETURN:
                console.log("EasyGuideMapsEngine." + oEvent.functionName + "(" + oEvent.functionArguments.join(", ") + ") return callback value is '" + JSON.stringify(oEvent.returnValue) + "'");
                break;
            default:
                console.log("Unsupported easyGuide maps engine event " + oEvent.id);
        }
    
    }
https://www.gps-coordinates.net is a helpful online Look-Up tool when working with geo coordinates.

Methods

All EasyGuideMapsEngine asynchronous methods return a Promise object.

oEasyGuideMapsEngine.get("zoom").then(function(nZoom) { 
    console.log(nZoom);
});
or
async function printLayer() {
    var sLayerId = await oEasyGuideMapsEngine.get("layer");
    console.log(sLayerId);
}
printLayer();

In addition the callback (if set) will be called with the event-id EasyGuideMapsEngine.EVENT_FUNCTION_RETURN and the properties functionName: string, functionArguments: any[] and returnValue: any.

It is recommended to use Promises instead of the EasyGuideMapsEngine.EVENT_FUNCTION_RETURN event, as the support for the callback might be dropped in future.
  1. toString()

    The method EasyGuideMapsEngine.toString(): string returns the name and version number of the easyGuide maps engine library.

    Returns (async):

    sClassName: string: Returns the class name with version number.

    Example:

    console.log(oEasyGuideMapsEngine.toString());  // "EasyGuide maps engine V#.#.#"
  2. refresh()

    The method EasyGuideMapsEngine.refresh(): void forces a map re-rendering of the map. This can be necessary if the size of the parent <div> container is changed and distortions are encountered.

    Returns (async):

    bSuccess: boolean: A flag to indicate the success of the function call.

    Example:

    oEasyGuideMapsEngine.refresh();  // refresh the map
  3. reset()

    The method EasyGuideMapsEngine.reset(): void resets the map to the initial viewport without changing the current layer.

    Returns (async):

    bSuccess: boolean: A flag to indicate the success of the function call.

    Example:

    oEasyGuideMapsEngine.reset(); // center the map
  4. screenshot()

    The method EasyGuideMapsEngine.screenshot(): void creates a screenshot of the current viewport without controls.

    Returns (async):

    oScreenshot: HTMLImageElement: An image object with width, height and src properties.

    Example:

    oEasyGuideMapsEngine.screenshot(); // take a screenshot of current viewport
  5. retrieve()

    The method EasyGuideMapsEngine.retrieve(sElementType: string, oEasyGuideMapsEngineRetrieveOptions?: object): void retrieves a list of ids for the given element type.

    Arguments:

    1. sElementType: string: The type ("layers"|"highlighters"|"points"|"icons") of element to retrieve.

      # type format (regex) description
      1 layers L[0-9]{2} The list of layers (= floors / level) of the building
      2 highlighters L[0-9]{2}P[0-9]{4} The list of selectable surfaces
      3 points L[0-9]{2}P[0-9]{4} The list of route point
      4 icons L[0-9]{2}P[0-9]{4} The list of icons
      5 texts L[0-9]{2}P[0-9]{4} The list of texts
    2. oEasyGuideMapsEngineRetrieveOptions: object: An optional object literal to configure the behavior as follows:

      # key value description
      1 visible-only bVisibleonly: boolean Returns only elements that are currently visible on the map when set to true. Default value is false.

    Returns (async):

    oElementsIdsList: string[]: The list of ids for the given element type.

    Example:

    oEasyGuideMapsEngine.retrieve("icons", { "visible-only": true });  // [L01P2013, L01P2016, L01P9015]
  6. retrieveClosestElementsByCoordinates()

    The method EasyGuideMapsEngine.retrieveClosestElementsByCoordinates(oLongitudeLatitudeCoordinates: number[], sLayerId: string): void retrieves a list of the three closest elements within the given layer for the given geo-coordinates in the commonly used WGS (= EPSG:4326) format.

    Arguments:

    1. oLongitudeLatitudeCoordinates: number[]: The geo-coordinates ([longitude: number, latitude: number])
    2. sLayerId: string: The layer id (default: current layer)

    Returns (async):

    oClosestElementsIdsList: string[]: The list of point ids closest to the given coordinates.

    Example:

    oEasyGuideMapsEngine.retrieveClosestElementsByCoordinates([24.81077805, 60.21808025], "L03");  // [L03P1216, L03P1217, L03P1215]

    Use this method to find the closest supported point based on geo-coordinates provided by user events (see this example) or indoor positioning systems (IPS).

  7. get()

    The method EasyGuideMapsEngine.get(sSettingKey: string): void gets the value of a specific setting.

    Arguments:

    1. sSettingKey: string: The setting key ("layer"|"zoom"|"rotation"|"padding"|"start"|"end"|"section"|"line-of-sight|"flood").
    # key value description
    1 layer sLayerId: string Gets the current layer of the map.
    2 zoom nZoom: number Gets the current zoom level of the map with values between 0 (= min) and 1 (= max). There are 8 zoom levels, thus the zoom step size is 1 / 8 = 0.125.
    3 rotation nRotation: number Gets the current rotation of the map in radian with values between 0 and 2π (= 6.28318530718)
    4 padding oPadding: number[] Gets the current padding (top, right, bottom, left) of the map with values between 0 (= min) and 1 (= max).
    5 start sPointId: string Gets the current start marker (red) of the map. Returns null if the start marker is currently not set.
    6 end sPointId: string Gets the current end marker (black) of the map. Returns null if the end marker is currently not set.
    7 section nSectionIndex: number Gets the current route section. Returns null if a route is currently not set.
    8 line-of-sight nLineOfSight: number Gets the line-of-sight rotation angle at the start marker. Returns null if no line-of-sight currently not set.
    9 flood bRunningStatus: boolean Gets the flood animation status. Returns false if a flood animation is currently running and false otherwise.

    Returns (async):

    sSettingValue: any: The current setting value.

    Example:

    oEasyGuideMapsEngine.get("zoom");  // 1 = maximum zoom level
  8. set()

    The method EasyGuideMapsEngine.set(sSettingKey: string, sSettingValue: string): void sets the value of a specific setting.

    Arguments:

    1. sSettingKey: string: The setting key ("layer"|"zoom"|"rotation"|"padding"|"start"|"end"|"section"|"line-of-sight|"flood").
    2. sSettingValue: string: The setting value.
    # key value description
    4 padding oPadding: number[] Sets the padding (top, right, bottom, left) of the map with values between 0 (= min) and 1 (= max).
    2 zoom nZoom: number Sets the zoom level of the map with values between 0 (= min) and 1 (= max). The minimum zoom step size is 1 / 8 = 0.125.
    3 rotation nRotation: number Sets the rotation of the map in radian with values between 0 and 2π (= 6.28318530718)
    1 layer sLayerId: string Sets the layer of the map. The list of supported layers can be retrieved via oEasyGuideMapsEngine.retrieve("layers")
    5 start sPointId: string Sets the start marker (red) of the map. The list of supported points can be retrieved via oEasyGuideMapsEngine.retrieve("points"). Pass null to remove the end marker
    6 end sPointId: string Sets the end marker (black) of the map. The list of supported points can be retrieved via oEasyGuideMapsEngine.retrieve("points"). Pass null to remove the end marker
    7 section nSectionIndex: number Sets the route section and focuses the map on it. Valid values are integer values from 0 (= first route section) to oRouteLayersIdsList.length-1 (= last route section)
    8 line-of-sight nLineOfSight: number Sets the line-of-sight rotation angle at the start marker in radian with values between 0 and 2π (= 6.28318530718). The line-of-sight is only applicable if a start marker is currently set.
    9 flood bRunningStatus: boolean Sets the flood animation status. Passing true will start the flood animation.

    Returns (async):

    sNewSettingValue: any: The new current setting value.

    Example:

    oEasyGuideMapsEngine.set("layer", "L01");  // switch to layer L01

    The padding allows you to take into account overlay elements. See this example.

  9. route()

    The method EasyGuideMapsEngine.route(oWayPointsIdsList: string[], oEasyGuideMapsEngineRouteOptions?: object): void displays a route on the map. A previously displayed route is removed if required.

    Arguments:

    1. oWayPointsIdsList: [sStartPointId: string, sEndPointId: string]: The start and end point. Pass null to remove an existing route.
    2. oEasyGuideMapsEngineRouteOptions: object (optional): An optional object literal to configure the behavior as follows:
    # key value description
    1 preload bPreload: boolean Use preloaded route calculations if available (project dependent). Default value is false.
    2 dryrun bDryrun: boolean In dryrun mode the method returns the same values as in normal mode but doesn’t display a route. This can be helpful if you need to know a rout’s distance and duration without displaying it. Default value is false.
    3 optimization bOptimization: boolean With optimization enabled, the route will automatically be simplified to less route points / sections without a visible impact.
    4 accessible bAccessible: boolean The flag to use an alternative accessible route avoiding stairs, escalators or similar obstacles. Default value is false.
    5 redirect oRedirect: string[] You can pass alternative destinations [e.g. L##P####] for the route (e.g. other entrances). The algorithms will automatically determine the quickest (based on the route duration) route and redirect to it. Default value is []

    Returns (async):

    { distance: number, duration: number, layers: string[], points: [ id: string, layer: string, link: { distance: number, duration: number, point: string, type: string }, position: { // preload only longitude: number, latitude: number, elevation: number }, angle: number // preload only ] } : The object literal with the route distance (in meter), duration (in seconds) and associated layers and points.

    Example:

    oEasyGuideMapsEngine.route(["L02P2013", "L04P2146"], { "accessible": true });  // display the accessible route from point L02P2013 to L04P2146

    The map is NOT automatically switched to the layer of the given start point. Use EasyGuideMapsEngine.set("section", 0) to focus on the first route section.

    The points.link.type can have the following values: 'default', 'other', 'stair-up', 'stair-down', 'escalator-up', 'escalator-down', 'lift-up', 'lift-down', 'ramp-up', 'ramp-down', 'not-escalator-up', 'not-escalator-down', 'disabled', 'closed'

  10. focus()

    The method EasyGuideMapsEngine.focus(sElementId: string, oEasyGuideMapsEngineFocusOptions?: object): void centers the map over a given element. If required the layer is switched automatically to the layer of the target element.

    Arguments:

    1. sElementId: string: The element to focus on. Pass null to focus on the current map center.
    2. oEasyGuideMapsEngineFocusOptions: object (optional): An optional object literal to configure the behavior as follows:

      # key value description
      1 zoom nZoom: number The target zoom level between 0 (= min) and 1 (= max). Default value is the current zoom level.
      2 rotation nRotation: number The target rotation between between 0 and 2π (= 6.28318530718) . Default value is the current rotation.
      3 duration nAnimationDuration: number The target animation duration in seconds between 0 (= instant change) and 10 (= ten seconds animation). Default value is a 1 seconds animation.

    Returns (async):

    bSuccess: boolean: A flag to indicate the success of the function.

    Example:

    oEasyGuideMapsEngine.focus("L03P2273", 1, 3);  // maximum zoom on element L03P2273 within 3 seconds animation

    Combining the different options allows you to create smooth map animations. See this example.

  11. highlight()

    The method EasyGuideMapsEngine.highlight(oElementsToHighlightIdsList: string[], sFillColor: string, sStrokeColor: string, sHighlightMode: string): void highlights elements on the map.

    Arguments:

    1. oElementsToHighlightIdsList: string[]: The list of elements to set, add or remove. Pass null to remove all current highlighters.
    2. sFillColor: string: The fill color for the element. Valid values are any CSS color code. For no-fill pass null.
    3. sStrokeColor: string: The stroke color for the element. Valid values are any CSS color code. For no-stroke pass null.
    4. sHighlightMode: string: The mode (EasyGuideMapsEngine.HIGHLIGHT_SET, EasyGuideMapsEngine.HIGHLIGHT_ADD or EasyGuideMapsEngine.HIGHLIGHT_REMOVE).

    Returns (async):

    oElementsCurrentlyHighlightedIdsList: string[]: The list of ids of currently highlighted elements.

    Example:

    oEasyGuideMapsEngine.highlight(["L02P2061", "L03P2273"], "rgba(255, 0, 0, 0.5)", "#000000", EasyGuideMapsEngine.HIGHLIGHT_SET);  // highlight surface L02P2061 & L03P2273 with a semi-transparent red filling and a black border
  12. popup()

    The method EasyGuideMapsEngine.popup(sElementId: string, sHtml: string, oEasyGuideMapsEnginePopupOptions?: object): void displays a popup above the given element.

    Arguments:

    1. sElementId: string: The element above which the popup shall be displayed. Pass null to remove a currently visible popup.
    2. sHtml: string: The HTML content to display.
    3. oEasyGuideMapsEnginePopupOptions: object (optional): An optional object literal to configure the behavior as follows:

      # key value description
      1 close-button bCloseButton: boolean The flag to show or hide the closing-✖ button at the top right corner.
      2 auto-pan bAutoPan: boolean The flag to enable or disable the auto-pan feature, making the popup automatically fully visible when enabled.
      3 anchor sAnchor: string The anchor ("point", "icon", "text", "highlighter") for the popup. Default and fallback is "point".

    Returns (async):

    bSuccess: boolean: A flag to indicate the success of the function.

    Example:

    oEasyGuideMapsEngine.popup("L02P2061", "<video controls style='width:272px;height:153px;' src='https://www.easy-guide.mobi/res/mp4/MyVideo.mp4'/>", { "close-button": true, "auto-pan": true, "anchor": "icon" });  // display a popup with a video player above the icon L02P2061

    As the easyGuide maps engine is based on cross-origin communication you cannot add event-listener to the HTML-elements you pass as an argument. However any element you give an id-attribute will fire the EasyGuideMapsEngine.EVENT_POPUP_ELEMENT_SELECTED event with the element-id. See this example.

Download

You can view and download a simple one file example here for you to upload on any webserver for testing purposes.

History

History:

# Version Description
1 V0.3.8 New popup option "auto-pan"; new get/set option "padding"; improved text kerning; small bug fixes;
2 V0.3.7 New rotation event; new route() option "optimization"; new retrieve() option "visible-only"; performance improvements, style improvements;
3 V0.3.6 Improved styles for routes; controls and popups; enhanced level of detail; new events (zoom and user interaction); new route options; performance improvements;
4 V0.3.5 New "line-of-sight" getter/setter property to indicate current looking direction of the user.
5 V0.3.4 The event EasyGuideMapsEngine.EVENT_POPUP_ELEMENT_SELECTED is fired when an HTML-element with an id-attribute is selected inside the popup.