Navizon  I.T.S. Documentation

API - Overview

Navizon I.T.S. exposes a RESTful web API that can be used to access and manipulate the state of set of resources registered with a site. The available resources are:

The API is accessed using URIs that points to the resource to be manipulated. For example, the URI:

http://its.navizon.com/api/v1/sites/1001/nodes/7072CF2148F0/

refers to the node with MAC address 7072CF2148F0 installed at site with ID 1001.

Operations on resources are controlled by using one of the following HTTP methods:

The list of resources and supported HTTP methods is available in the reference page.

Accessing the API using cUrl

The easiest way to access the API is via the command line tool curl freely available at http://curl.haxx.se/. Using curl, it is possible to supply user credentials using necessary to access a resource. Example:

    curl -u username:password http://its.navizon.com/api/v1/sites/1001/nodes/7072CF2148F0/

By default, the HTTP method GET is invoked on the resource. Other methods can be called with the -X option. Examples:

    curl -u username:password -X PUT http://its.navizon.com/api/v1/...

    curl -u username:password -X DELETE http://its.navizon.com/api/v1/...

Resource Identifiers

multi-level site

Site ID

In Navizon I.T.S., resources are accessed in the context of a particular site. Sites are identified by short alphanumeric strings (the siteId) that are assigned by Navizon. You should have received the site identifier by email when your Navizon I.T.S. account was created. The siteId can be also found in the Advanced Setting tab of the user interface available at http://its.navizon.com.

Level ID

Nodes deployed in multi-story buildings can be grouped into levels, which are identified by numeric IDs. By default, all the nodes added to a newly created site are placed on the default level (levelId = 0). More levels can be created to capture the 3D geometry of the deployment site.

MAC Addresses

Nodes and stations within a site are identified by their MAC addresses. For nodes, the MAC address is printed on a small label on the bottom of the devices. For stations, you will have to consult the documentation of your operating system in order to find the MAC address of the WiFi card.

MAC addresses be can expressed in three different formats: A) 000000000000, B) 00:00:00:00:00:00, C) 00-00-00-00-00-00.

Example: The following URIs contain valid MAC addresses that points to the same resource

Additionally, it's possible to associate a name and description to the nodes in the system and known WiFi stations. Adding a name to a station's MAC address makes it easier to track this device in busy environments.

User accounts

Access to Navizon I.T.S. resources is restricted to registered users on a per-site basis. Each account is identified by an username (an email address) and a password. The list of sites associated with account is available by querying the global site resource:

    http://its.navizon.com/api/v1/sites/

Example: the command

curl -u username:password http://its.navizon.com/api/v1/sites/
    

returns a JSON representation of the sites registered with the account defined by username:password

[  {
        "siteId": "1001",
        "name": "Site A",
        ...
    },
    {
        "siteId": "1002",
        "name": "Site B",
        ...
    },
    ...
]

Navizon I.T.S. defines three possible access levels for each user account registered with a site:

Users with Read-Only access are not allowed to make changes to the site, while users with Read-Write access can modify data regarding nodes and station. Full control access is required to create and delete user accounts within a specific site. The access level for a particular site is returned by querying the site resource:

Example: the command:

        curl -u username:password http://its.navizon.com/api/v1/sites/1001/
    

returns the site's information and the access field.

        {
            "siteId": "1001",
            "name": "Site A",
            "access": "30"
            ...
        }
    

Access to Location Information

Navizon I.T.S. is designed to track the locations of WiFi stations active within a site. Location can be accessed synchronously or asynchronously via a callback mechanism.
synchronous and asynchronous access

Synchronous Access

The synchronous interface is used to query the location of a station within a specific site. The URI for the query is composed by combining the siteId with the MAC address of the station to track. For example, the URI

http://its.navizon.com/api/v1/sites/1001/stations/00237698BDEC/

provides access to the information available in site 1001 about the station with MAC address 00:23:76:98:BD:EC. The Quick Start section contains examples written in different programming languages that show how to query the service and parse the JSON results.

The API also allows the developer to retrieve the locations of all the stations active within a site. In this case, the URI only contains a reference to the siteId:

http://its.navizon.com/api/v1/sites/1001/stations/

Since the number of stations active within a site can be potentially large, it is possible to filter the results by only querying those stations that were active in a specified time interval, for example in the last five minutes. The list of query parameters is available in the reference section.

JSON Representation of Station Information

The location of station is represented in JSON format as in the following example:

{
    "mac": "485B394AC5E9"
    "name": "MyDevice",
    "desc": "Smart Phone",
    "siteId": "1001",
    "lrrt": 1,
    "loc": {
            "levelId": 0,
            "lng": -117.114337,
            "lat": 32.911862
    },
}

NOTES:

Asynchronous Access (Callback Mechanism)

The asynchronous interface allows the user to define a list of stations to monitor and a callback URL that will be invoked when the position of any of these stations changes. A JSON representation of the devices will be POSTED to the user-defined URL. The service rate is limited to a maximum of one notification every five seconds, and each call will contain information about all the devices whose location has changed since the last notification.

Steps to enable the callback service:

  1. Activate a web server on an URL where you will receive the notifications. In the following examples, we will assume that your server is accessible (make sure the URL is accessible from outside the firewall) at:
    http://my.domain.com/ItsPost.php
  2. Associate the callback URL to your site:
    curl -u username:password -X PUT -d "url=http://my.domain.com/ItsPost.php" its.navizon.com/api/v1/sites/{siteId}/callbacks/
            
  3. Register the MAC address of any station you want to be notified about:
    curl -u username:password -X PUT its.navizon.com/api/v1/sites/{siteId}/callbacks/stations/{mac}/
            

Other operations:

To retrieve the MAC addresses of the stations registered in the callback list:

    curl -u username:password its.navizon.com/api/v1/sites/{siteId}/callbacks/stations/

To remove a station from the callback list:

    curl -u username:password -X DELETE its.navizon.com/api/v1/sites/{siteId}/callbacks/stations/{mac}/

To disable all the notifications, delete the callback URL:

    curl -u username:password -X DELETE its.navizon.com/api/v1/sites/{siteId}/callbacks/

Low-Level Callback Mechanism

The callback mechanism described above operates at the site level, i.e. the callback URL will be invoked when the position of a station changes within the site. In addition to this service, Navizon I.T.S. also provides a lower level mechanism that operates at the node level. When a station is registered in the callback list of a specific node, the callback URL will be invoked when the node detects the station in its radio range. This service can be used to implement location based applications, triggered by the proximity of a station to a particular node. For example, you can implement a system that automatically checks-in users when their devices are detected by a specific node in the system.

The steps to add or remove devices from the callback list of a node are similar to the steps described for the general callback mechanism.

To add a station to the callback list of a node:

    curl -u username:password -X PUT its.navizon.com/api/v1/sites/{siteId}/callbacks/nodes/{nodeMac}/stations/{stationMac}/

To delete a station from the callback list of a node:

    curl -u username:password -X DELETE its.navizon.com/api/v1/sites/{siteId}/callbacks/nodes/{nodeMac}/stations/{stationMac}/

JSON representation of the data POSTED to the callback URL

{
    "time": 1324416340589,
    "siteNotifications": [
        {
            "mac": "0072CF1733B1",
            "loc": {
                "lat": 32.797544,
                "lng": -117.249093,
                "levelId": 0
            },
            "lrrt": 3,
            "siteId": "1001"
        },
        {
            "mac": ...
            ...
        }
    ],
    "nodeNotifications": [
        {
            "node": "AC8674022A38",
            "stations": [
                {
                    "mac": "00237698BDEC",
                    "lrrt": 3,
                    "rss": -33
                },
                {
                    "mac": "AC867401EF03",
                    "lrrt": 3,
                    "rss": -43
                }
            ]
        }
    ]
}

The data posted by the server contains two arrays: siteNotifications and nodeNotifications.