Embedded Location Intelligence

Getting Started with Galigeo API™

With this guide, you will be able to

Understand the main concepts behind the API
Get familiar with the structure of the API calls
Create your first API call
Bonus: Embed your first map in Microsoft Sharepoint™

What is Galigeo API™

Galigeo API™, or simply called API, is a REST webservice that lets you embed the Galigeo Location Intelligence solution everywhere you want (third-party applications, portals, websites, ...).

Its purpose its to offer to any user communities to augment any applications people are already familiar or used to work with, with self-service geospatial capabilities, to create and share meaningful geospatial analysis and map visualizations.

Its promise is to able to embed geospatial capabilities anywhere with the least code development possible and in the shortest time.

Prerequisites

Before getting started with the API, make sure the followings points are on tracks.

You have an account on Galigeo Cloud

The Galigeo Web Application is deployed on a J2EE Tomcat/JAVA Application Server
The Application Server is started and correctly set

When manipulating the API, for example defining the parameters, its recommended to use an advanced text-editor, like Notepad++. Such editors are mostly free to use.

Still do not have the product? Contact us for a trial

Main Concepts

The Galigeo API™ is available in the form of a RESTful webservice.

The parameters requested by the API are in JSON format.

When making a call, the webservice parameters are sent through POST method.
Other methods like GET are currently not supported.

The webservice can be used in both server-to-server or client-to-server calls.

What needs the API?

The API accepts a set of parameters to work properly.

The parameters can be divided into two core families:

Map Metadata
Data

The Map Metadata defines the core properties associated to the visualization you are going to embed, such its ID, name or lang.

The Data defines the data in JSON format that will feed the map.

We are going to focus on the core parameters used to define the Map Metadata, and see how to define the Data parameter later.

First, start by defining the mapId parameter.

This parameter is mandatory.

Its a unique ID that will be used to identify the map you will embed throughout itd whole life.

Once defined, you won't be able to change it.

You also need to make sure that each webservice will have a unique ID to avoid collision.

The ID cannot contain special characters, underscores, or whitespaces in it name. Its length does not matter tho.

Some ID examples: EmbeddedMapInPortal, MapForSAP, MapForPowerBI, ggomap1234, ...

Second, define the user parameter.

Even if this parameter is not mandatory, it's highly recommended to explictly define it when calling the webservice.

It defines the level of rights the service caller will have: Administrator, Author, End User, ...

For example, an Author will be able to create new thematics on the map, while the End User will only have access to read-features mode

If this parameter is ommitted, the map will open in read-only mode (equivalent to End User).

Below is an example of valid metadata parameters. This will be our foundation for getting started.

Note that the data parameter has been ommitted here, see next section to learn more about the this parameter.

{
			"mapId" : "MyFirstEmbeddedMap",
			"user"  : "Administrator"
			}

Feed the API with Data

In order to work, the webservice requires data. The data will then become available for the map to be able to show something.

Its detailed structure goes as follow.

"data" : [{"fields": [{...}, {...}, ...], "features": [{...}, {...}, ...]}, {...}]

Note that multiple datasets can be passed in the data parameter structure.

Each dataset is composed by two key elements: fields and features.

Fields

The fields element contains the metadata associated to each of the dataset dimension/column names.

You can define as many dimensions/columns as you want.

"fields" : [
			{
			"name" : "NAME",
			"alias" : "Name",
			"type" : "esriFieldTypeString",
			"dimension": true
			},
			{
			"name" : "INDICATOR",
			"alias" : "My indicator",
			"type" : "esriFieldTypeDouble",
			"dimension": false
			}
			]

Please take into account the following restriction regarding the defined metada.

No special characters or spaces in the “name” attribute. It will be internally used by the application.
The alphanumerical fields are always of esriFieldTypeString type; the numerical fields are always of esriFieldTypeDouble type.
It is the "alias" attribute that is presented in the application user interface. It can contain special characters and spaces.
The "dimension" attribute designates a dimension if it is set to true, and an indicator if it is set to false.

Features

The features element consists in a list of object defining the attribute values for each field defined in the fields element.

You can add as many objects as you want.

"features" : [
			{
			"attributes" : {
			"NAME" : "COMM MANUFACTURING",
			"INDICATOR" : 432351.0
			}
			},
			{
			"attributes" : {
			"NAME" : "COMM SAFETY",
			"INDICATOR" : 503096.0
			}
			}
			]

Below is an example of a valid data parameters

"data":  [{
			"fields" : [{
			"name": "x",
			"alias": "x",
			"type": "esriFieldTypeDouble",
			"dimension": false
			}, {
			"name": "y",
			"alias": "y",
			"type": "esriFieldTypeDouble",
			"dimension": false
			}, {
			"name": "location",
			"alias": "location",
			"type": "esriFieldTypeString",
			"dimension": true
			}, {
			"name": "address",
			"alias": "address",
			"type": "esriFieldTypeString",
			"dimension": true
			}],
			"features" : [{
			"attributes" : {
			"x" : 2.2918590903282166,
			"y" : 48.85893228504392,
			"location": "Event Q1 - Customer Success",
			"address" : "Quai de Suffren, Paris"
			}
			}]
			}]

Testing the Webservice

Once you have define the parameters, you may want to test the webservice first.

You can use our Online Tester where you can past your parameters for testing purpose.

You can go to http://<APP-SERVER>:<APP-PORT>/Galigeo/viewer/jsp/openMapRestTest.jsp in order to test the behaviour of the webservice regarding your parameters, and see a result live.

Using our sample, our set of parameters looks like this

{
			"mapId" : "MyFirstEmbeddedMap",
			"user"  : "Administrator",
			"data":  [{
			"fields" : [{
			"name": "x",
			"alias": "x",
			"type": "esriFieldTypeDouble",
			"dimension": false
			}, {
			"name": "y",
			"alias": "y",
			"type": "esriFieldTypeDouble",
			"dimension": false
			}, {
			"name": "location",
			"alias": "location",
			"type": "esriFieldTypeString",
			"dimension": true
			}, {
			"name": "address",
			"alias": "address",
			"type": "esriFieldTypeString",
			"dimension": true
			}],
			"features" : [{
			"attributes" : {
			"x" : 2.2918590903282166,
			"y" : 48.85893228504392,
			"location": "Event Q1 - Customer Success",
			"address" : "Quai de Suffren, Paris"
			}
			}]
			}]

When creating your parameters structure in JSON, if you are not sure if the syntax of your parameters is correct, you can try it on website like JSON Lint.

Check Call Responses

When calling the webservice, it can happen that it won't give you an anwer back. This can be caused by the fact that for example, a mandatory parameter has been forgotten, or the data structure is invalid.

To check that, you can open your browser console by pressing F12, and navigate to the "Network" tab. From there, you will be able to track the calls the API is going to make.

You can receive one of the following responses:

Response OK / KO	JSON Response Example	Comments
OK	{ "status" : "200", "url" : "<GGO-HTML5-WEB-CLIENT-URL>" }	The "url" parameter represents the Galigeo HTML5 Viewer URL to be called from the web client of the Enterprise portal, from for instance an HTML iframe.
KO	{"status": "400","message": "mapId not found or empty"}	In this instance the mandatory parameter ?mapId? is missing in the POST JSON.
KO	{ "status" : "400", "message" : "data not found or empty" }	In this instance the "data" attribute of the POST JSON was not sent.
KO	{ "status": "500", "message": "A JSONObject text must begin with \'{\' at character 1" }	The display process of the map cannot continue. In this instance, the posted JSON has a structure problem.