01 – REST API Quickstart guide

Situm REST APIs are a set of APIs that will allow you to manage and consume (full CRUD) all your information programmatically: cartography, geolocations, etc.

• Retrieve your cartography, including floorplans, POIs and geofences, from any system. You may enrich your webpage or digital kiosks with beautiful maps and POI directories, or provide your visitors with turn by turn wayfinding directions from any digital kiosk.
• Retrieve indoor & outdoor geolocation data: historical or in real time. You may integrate out-of-the-box geospatial analytics such as heatmaps, trajectories, or geofencing-based reports in your web apps and BI dashboards.

Our APIs are documented following the OpenAPI specification. You may consume them with most HTTP clients & libraries: we recommend curl from the command line or Postman if you prefer a GUI.

Before you start #

Before you start, you will need an account in Situm Dashboard and an API KEY. To have some testing data, we recommend to create a building, calibrate it, and generate some positioning data with Situm Mapping Tool.

Public and Beta APIs #

We support 2 different APIs:

• Public. This is the main API, and the one you should use in most cases. It contains all the main methods & resources that are stable enough for production usage.
• Beta. This is the API where we push our methods & resources while they are in an experimental phase. You can try them out but we do not recommend to use them in production services. Eventually, methods & resources will transition from beta to public.

Authentication & Authorization #

All requests must be authenticated. We allow three methods. 

JWT Bearer (RECOMMENDED) #

Headers contain a JWT token. To retrieve a JWT, you may use this API call. For example:

//Example using the email user@email.com and JWT eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiMjCJlbWFpbCI6InFhLmFjYW5lZG9Ac2l0dW0uZXMi
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiMjCJlbWFpbCI6InFhLmFjYW5lZG9Ac2l0dW0uZXMi' 'https://dashboard.situm.com/api/v1/buildings'

APIKEY #

Headers contain the user APIKEY. You may create your APIKEY following this doc. Sample usage:

//Example using the APIKEY T9NPlzk+jSI/Oi5DG6ODk57O0pZXdx4
curl -H 'X-API-KEY: T9NPlzk+jSI/Oi5DG6ODk57O0pZXdx4' 'https://dashboard.situm.com/api/v1/buildings'

There are three types of API Keys that restrict access to endpoints. From less to more restrictive:

• Read-write: This API key can operate without restrictions and invoke all the endpoints of the Situm API. Please, be careful when using this type of API key.
• Read-only: Allows positioning and executing all GET requests to the Situm API.
• Positioning: Allows positioning. We highly recommend using this type for mobile applications.

Basic Auth (NOT RECOMMENDED) #

A header field in the form of Authorization: Basic CREDENTIALS must be provided. CREDENTIALS is the Base64 encoding of the user email and password joined by a single colon “:”. See RFC7617 for details.

//Example using the base64 encoding of user@email.com:1234 
 curl -H 'Authorization: Basic dXNlckBlbWFpbC5jb206MTIzNA==' https://dashboard.situm.com/api/v1/buildings

First steps #

We will start by creating a JWT token that we will use to authenticate all the subsequent API requests.

curl -X POST -H 'X-API-KEY: $YOURAPIKEY' 'https://dashboard.situm.com/api/v1/auth/access_tokens' 

The previous call should return a JWT token like this one:

{
    "access_token": "AAAAAAAAAAAAAAAAAAAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDEEEEEEEEEEEEEEEEEEEEEEEEEFFFFFFFFFFFFFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGGGGGGHHHHHHHHHHHHHHHHHHHHHHHHIIIIIIIIIIIIIIIIIIIIIIIIIJJJJJJJJJJJJJJJJJJJJJJKKKKKKKKKKKKKKKKKKKKLLLLLLLLLLLLLLLLLLLLLLLMMMMMMMMMMMMMMMMMMMM"
}

Now we can use this token, for example, to retrieve all the buildings in our account:

curl -X GET -H 'Authorization: Bearer $YOURJWTTOKEN' 'https://dashboard.situm.com/api/v1/buildings'

Returning an array of JSON objects, each one containing the information of a certain building (name, when it was created, its location, etc.):

[
    {
        "id": 6545,
        "user_uuid": "a2271ae1-ab66-4b3b-b669-72a5b67b01be",
        "name": "Situm HQ",
        "description": null,
        "created_at": "2020-02-05T16:57:39.597+01:00",
        "updated_at": "2021-03-26T22:22:39.645+01:00",
        "location": {
            "lat": 43.3556157453238,
            "lng": -8.41359581615905
        },
....

You may also retrieve all the cartography elements, such as floorplans, geofences or points of interest. For instance, we may retrieve the POIs of the building 6545 (one of the buildings of our account, as shown in the previous response):

curl -X GET -H 'Authorization: Bearer $YOURJWTTOKEN' 'https://dashboard.situm.com/api/v1/pois?building_id=6545'

Another example: we can retrieve all the positioning data of all the users that are positioning in our building right now.

curl -X GET -H 'Authorization: Bearer $YOURJWTTOKEN' 'https://dashboard.situm.com/api/v1/realtime/building/6545'

And we can also retrieve all the historical positioning data of the users of a building (e.g. 6545) between two date-times (e.g. from 2021-06-24T00:00:00.000Z to 2021-06-25T00:00:00.000Z):

curl -X GET -H 'Authorization: Bearer $YOURJWTTOKEN' 'https://dashboard.situm.com/api/v1/analytics/raw_pose_data?building_id=6545&date=2021-06-24T00:00:00.000Z&date_end=2021-06-25T00:00:00.000Z' 

That’s it! As you can see, using Situm REST API is a no-brainer. With this base, you will be able to read & modify all your cartography data (floorplans, geofences, paths, pois…), manage all the users registered in Situm platform, retrieve all your geodata, generate geoanalytics and much more.

Take a look at the full OpenAPI spec of our public and beta API to learn more about all these possibilities.

Using the REST API with different tools #

Situm REST APIs can be used and consumed with a wide range of tools: CURL, Swagger, Postman or any of your favourite client libraries, to name just a few. In this section, we provide a quick start guide of Swagger.

Swagger Editor #

You may use both our Public and Beta APIs with Swagger editor. This editor provides a web GUI, where you can read the documentation and test the API endpoints at the same time.

First, download the API YAML specification from the API specification webpage.

Then, go to the Swagger Editor and import the YAML file (e.g. situm_public_api.yaml).

Finally, the yaml file will be uploaded and ready to use.