Positioning API (beta)

Self-contained code examples can be found on Github and the full API reference is available here.

Overview

IndoorAtlas Positioning REST API allows rough-accuracy tracking of any devices that are able to scan their surrounding Wi-Fi environment. This service is ideal for devices that are not able to run the full IndoorAtlas SDK such as wearables, IoT devices or even PCs.

For tracking of mobile phones, it is highly recommended to use the IndoorAtlas SDKs for better accuracy.

Prerequisites

  • The relevant premises are mapped with Map Creator 2
  • The API key used is created with Positioning API scope enabled.

Example

To use the positioning API, the application must be able to read a Wi-Fi scan from the device. It is a list of observed Wi-Fi access point MAC addresses (BSSIDs) and the corresponding signal strengths (RSSIs in dBm).

To find the location of the device, the Wi-Fi scan is sent to the /locate endpoint of the API as the JSON payload of an HTTP POST request, for example:

curl -X POST "https://positioning-api.indooratlas.com/v1/locate?key=$APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"wifis":[
    {"macAddress":"06:18:d6:c1:c0:89","signalStrength":-55},
    {"macAddress":"de:99:ad:37:be:1c","signalStrength":-82}
  ]}'

which returns the corresponding coordinates, floor number and accuracy (uncertainty radius):

{
  "location": {
    "floorNumber": 7,
    "coordinates": {
      "lat": 60.17066855531062,
      "lon": 24.945905116025607
    },
    "accuracy": 10
  },
  "context": {
    "indooratlas": {
      "floorPlanId": "a314b673-d27d-4bd1-a9bf-bc0cdbd7147c",
      "venueId": "9760790b-4069-41d0-949a-3ed28ad2dbe8"
    }
  }
}

The response also includes the associated floor plan and location contexts as floorPlanId and venueId.

Venue API

The full metadata corresponding to the floorPlanId and venueId returned by the /locate endpoint can also be fetched from the API. For example

FLOOR_PLAN_ID=a314b673-d27d-4bd1-a9bf-bc0cdbd7147c
curl "https://positioning-api.indooratlas.com/v1/floor_plans/$FLOOR_PLAN_ID?key=$APIKEY"

returns

{
  "name": "Floor 4",
  "floorNumber": 4,
  "id": "a314b673-d27d-4bd1-a9bf-bc0cdbd7147c",
  "venueId": "9760790b-4069-41d0-949a-3ed28ad2dbe8",
  "image": {
    "url": "https://example.com/af4eb6ce-213b-4dc2-816a-a8b6998657fa",
    "height": 3307,
    "width": 2339,
    "widthMeters": 30.09341767991734,
    "heightMeters": 42.54764098652699,
    "metersToPixels": 77.72463815437345,
    "pixelsToMeters": 0.012865933167985183,
    "center": {
      "lat": 60.170568759612436,
      "lon": 24.945683777332306
    },
    "topLeft": {
      "lat": 60.17038459999827,
      "lon": 24.94597318695491
    },
    "bottomLeft": {
      "lat": 60.17076602968718,
      "lon": 24.945935824520134
    },
    "bottomRight": {
      "lat": 60.17075286193615,
      "lon": 24.945394370732014
    },
    "topRight": {
      "lat": 60.170371432247244,
      "lon": 24.94543173316679
    }
  }
}

and

VENUE_ID=9760790b-4069-41d0-949a-3ed28ad2dbe8
curl "https://positioning-api.indooratlas.com/v1/venues/$VENUE_ID?key=$APIKEY"

gives the list of all floor plans in that venue (a.k.a. location):

{
  "name": "Mikonkatu 13 Office",
  "id": "9760790b-4069-41d0-949a-3ed28ad2dbe8",
  "coordinates": {
    "lat": 60.1704947,
    "lon": 24.9456069
  },
  "floorPlans": [
    {
      "floorNumber": 3,
      "id": "75f42ddd-33ea-4122-8964-9ce2b84b15c5",
      "name": "Floor 3",
      "venueId": "9760790b-4069-41d0-949a-3ed28ad2dbe8",
      "image": { ... }
    },
    {
      "name": "Floor 4",
      "floorNumber": 4,
      "id": "a314b673-d27d-4bd1-a9bf-bc0cdbd7147c",
      "venueId": "9760790b-4069-41d0-949a-3ed28ad2dbe8",
      "image": { ... }
    }
  ]
}

Venue API can also used independently of positioning as demonstrated in the IndoorAtlas venue viewer example web app on Github.