Introduction

Smart World Web is a port of our Smart World Pro application software for the WebGL platform. It allows integration with other web applications that want to use our visualization tools for their business needs.

Accessing Smart World Web

There are two ways to access the application:

Free Mode

This mode only allows access to basic navigation of the map that defaults to New York, NY as wee as basic command access for map navegation and visualization. To access this mode just go to the following url:

https://api.swp.cityzenith.com/organization/swp/

Parameterized mode

The application can also receive a paremeter via its url that contains a series of parameters that the application will use at load time. The parameter is a base64 encoded string that is assigned to the url parameter "c".

https://api.swp.cityzenith.com/organization/swp/?c=<base64 string>

The encoded parameter must be of a stringified Json object that can load the following parameters 

  • The email and pass are the credentials to access Citizenith's Smart World API. 
  • The location is either a city or a specific address, not coordinates.
  • The lat_long is for coordinates only. 
  • The zoom determines how much of the map will be initially shown.
  • The style predetermines the style of the map before lading.
  • The project is the defined name of a project that will be loaded in the case it exists in the system for a logged in user.

Examples:

// javascript

// To simply login as a SmartWorld user:
var paramObj_1 = {"email": "email", "pass": "password"};

// To load a specific style:
var paramObj_2 = {"style": "Light"};

// To start at a particular location:
var paramObj_3 = {"location": "New York, NY"};

// To start at a particular location:
var paramObj_4 = {"lat_long": "40.756355, -73.987084"};

// A full parameter load:
var paramObj_5 = {"email": "email", "pass":"password", "project":"project", "location": "Tokyo, Japan", "style":"Light", "zoom": "16"};

var encodedParameter = window.btoa(json.stringify(paramObj_5));

__________________________________________________________________

SmartWorld Web API

SmartWorld Web allows integration to other web applications and provides a two way communication to send commands and receive information. The only condition is to place the player in an iframe with the url.

The commands to be sent to SmartWorld Web are being sent as strings in JSON format

// javascript

var command = {"command": "command", "args": {}}
var strCommand = json.stringify(command);

var iframeEl = document.getElementById('iframe_el');
iframeEl.contentWindow.postMessage(strCommand, '*');

Basic Map API

If the user is either an annonymus or an authenticated one, they will have access to the following API finctionality.

Change Location

{
    "command": "go_to_location",
    "args":
    {
        "location": "<city or address>" //Either location or lat_long
        "lat_long": "<lattitude>,<longitude>"
        [, "zoom_level": <zoom level>]
    }
}

This command changes a location to anywhere in the world that our Map API has registered. You can use ether the location to send an address, or a place in the world, or the lat_long parameter that contains the Geo-coordinates. The zoom_level optional argument allows to determine how much of the map will be seen after the reposition. the valuel it accepts are between 10 and 16.

Change Map Styles

{
    "command": "use_style"
    "args":
    {
        "style": "<style name>"
    }  
}

This command allows to change the style of the map for visualization and the style name is one of the following available styles for maps:

  • Cityzenith Dark.
  • Light.
  • Traffic Night.
  • Traffic Day.
  • Satellite Streets.
  • Le Shine.

Create Temporary Layers from Building Addresses 

{
    "command": "create_building_layer"
    "args":
    {
        "name": "<name of layer>",
        "buildings":
        [
            {
                "position": "<latitude, longitude>"[, "isSingleUnit" : <bool>][, "checkNearest" : <bool>]
            }
        ]    
        "color":"<color with alpha in hex format>"
        [,"zoom_to_view": <true or false>]
    }  
}

This command allows you to create layers based on the buildings that are normally displayed. The buildings array is an array if objects that must contain the latitude and longitude coordinates for each building in a string format of "lattitude, longitude" arrangement for the position, while the parameters isSingleUnit and  checkNearest are optional parameters to help the highlighting process. The color parameter is of the standard RGBA in hex values (i.e: "00FF00FF"). The zoom_to_view optional parameters commands the camera to zoom out and try to encompass all chosen buildings in one view.
These layers are not persistent since there is no logged in user and no project loaded.

The buildings that fit the layer will become clickable and will send an event with the following message structure

{
     "command": "building_selected",
     "response":
     {
          "status": 0,
          "message": OK",
          "payload":
          {
              latLong = "<lattitude, longitude>",
              address = "<building address, it can be null>"
          }
     }
}

Show/Hide Building Layers 

{
    "command": "show_building_layer"
    "args":
    {
        "name": "<name of layer>",
        "show": <true or false>
    }  
}

This command allows you to control how you show and hide layers that are created from the common buildings. The show parameters controls if the layer will show or hide (true or false respectively). The name parameter refers to the name of the layer to show or hide; if no name if provided, it assumes is the default building layer.

Remove a Layer

{
    "command": "remove_building_layer"
    "args":
    {
        "name": "<name of layer>",
    }  
}

This command will delete an existing building layer given the name.

SmartWorld API

Login

{
    "command": "login",
    "args":
    {
        "email": "<smartworld pro email>",
        "password": "<password>"
    }
}

Allows to either login after accessing the basic map or to change the user. If the login fails, a message will be displayed on screen.

Load Project

{
    "command": "load_project",
    "args":
    {
        "project_name": "<name of project in SmartWorld pro>"
        [,"relocate": <true or false>]
        [,"force_create": <true or false>]
    }
}

This command allows to load a project that currently exists in Smartworld Pro under the organization the user is in. The relocate optional parameter determines if after loading the project there will be a relocation to the last saved location or will load without moving. The force_create parameter will force the creation of a project if it does not exists in the system, if it's not present or set to false, if the project does not exists an error

Receiving Messages

To receive messages from the player in an iframe window the parent must be prepared to receive the event. The following snippet is an example to binf the event receiver and display the message:

// javascript

function bindEvent(element, eventName, eventHandler) {
    if (element.addEventListener){
        element.addEventListener(eventName, eventHandler, false);
    } else if (element.attachEvent) {
        element.attachEvent('on' + eventName, eventHandler);
    }
}

// This binds the message event to an alert function that displays the message from the iframe that contains the player
bindEvent(window, 'message', function (e) {
    alert(e.data);
});

The response messages are stringified json objects that follows the structure:

{
     "command": "command",
     "response":
     {
          "status": 0, //0:success, 1: error
          "message": "message for errors or OK",
          "payload": {object that contains the response. Can be null}
     }
}

Examples:

When the player is ready to receive commands it will send the following message:

{
     "command": "init",
     "response":
     {
          "status": 0,
          "message": OK",
          "payload": null
     }
}
Did this answer your question?