Fathom Locator API (2.0)

Download OpenAPI specification:Download

REST API

The Fathom REST API provides operations for configuring Fathom software and hardware, and for retrieving historical device positions.

JSON API Specification

The Fathom API is based on the JSON API Version 1.0 specification for REST APIs. Please refer to the JSON API documentation for further explanations and guidance on using JSON API.

Authentication

An API key is required to access the Fathom API. The API key must be included in the headers of each request to the Fathom API. The expected header name is 'x-api-key'.

Timestamp Format

All timestamps in the API are assumed to be in the format of milliseconds since UTC 1970.

Paged Data

For API queries that return too many records to fit in a single response, the API response will contain a 'continuationToken' string attribute. This continuation token can be passed as a query parameter to subsequent calls in order to retrieve the remaining records. The continuationToken will be omitted from the response once all of the records have been retrieved.

Streaming API

Fathom provides a WebSocket streaming interface for clients to receive events and device position messages from the Fathom SaaS platform. Clients connect to the WebSocket url, authenticate with the Fathom API, and then subscribe to specific topics of messages. Once subscribed, the clients will receive messages from each topic over the WebSocket connection.

WebSocket Subprotocol

Fathom uses deepstream.io’s open text-based subprotocol for communication over the WebSocket. Clients can either implement this subprotocol directly (see https://deepstream.io/tutorials/core/writing-a-client/) or use one of the open source language-specific SDK’s provided by deepstream.io.

The URL for the WebSocket interface is wss://stream.fathomsys.com

WebSocket Authentication

Clients authenticate with the WebSocket API using a private API key provided by Fathom. The API expects the following authentication object to be sent in the authentication request.

{
    apiKey: '<api key>'
}

Topics

The Fathom Streaming API contains a set of Topics that clients can subscribe to and receive filtered streams of messages.

In response to the stream authentication request, the API will return a list of topics that the API key is authorized to access. The response JSON object has a ‘topics’ key that contains a map value with keys ‘listen’ and ‘subscribe’. Each of these child keys map to arrays of topics on which the API key is authorized to listen or subscribe.

Example:

{
    topics: {
        listen: [],
        subscribe: [
            'topic/1234/5559/devices/positions',
            'topic/1234/5559/registered/devices/positions',
            'topic/1234/devices'
        ],
    }

The following topics are provided for each Organization venue. See the Message Types section of this document for descriptions of the types of events contained in each of these topics.

Device Position Topic

The Positions Topic contains a stream of device positions for each device in the venue, as they are calculated by the Fathom platform.

topic/<Organization Identifier>/<Venue Identifier>/devices/positions

Registered Device Position Topic

The Registered Device Positions Topic contains a stream of device venue positions for a configurable subset of registered devices identified in the Organization’s registered device list.

topic/<Organization Identifier>/<Venue Identifier>/registered/devices/positions

Device Information Topic

The Fathom Platform periodically sends device information for devices from all organization venues on the device information topic.

topic/<Organization Identifier>/devices

Message Types

Fathom publishes the following types of messages to the stream topics. Messages are formatted as JSON objects.

Device Position Messages

Device Position messages are real-time positions as calculated by the Fathom platform, with no filtering for stationary devices (as opposed to Position Change Events which are only generated when devices change position).

Format: { "timestamp": "The time of the event in msecs since 1970, UTC", "deviceId": "The unique ID of the device", "pos": { "lat": "The latitude of the device", long: The longitude of the device, alt: altitude of the device (optional field may not be present) } }

Example:

{
    "timestamp": 1531713841,
    "deviceId": "1234"
    "pos": {
        "lat": 53.2734,
        "long": -7.77832031
        "alt": 0
    }
}

Device Information Messages

Hub Information Update

Hub information updates are sent periodically to update information about the hub.

Format:

{

    "timestamp": "The time of the event in msecs since 1970, UTC",
    "eventType": "hubInfoUpdate",
    "venueId": "The unique ID of the venue",
    "deviceId": "The unique ID of the hub",
    "identification": {
        "mac": "the ethernet MAC address of the Hub",
        "macBle": "the bluetooth MAC address of the Hub",
        "macWifi": "the Wi-Fi MAC Address of the Hub",
        "name": "the bluetooth device name of the Hub",
        "model": "the model name of the Hub",
        "manufacturer": "the manufacturer name of the Hub ('Fathom')",
        "softwareVersion": "the software version of the Hub",
        "hostname": "the hostname of the Hub",
        "ipWifi": "the Wi-Fi IP address of the Hub",
        "ipEthernet": "the ethernet IP address of the Hub",
        "hardwareVersion": "the hardware version of the Hub ('FH-01-02')",
        "serial": "the serial number of the Hub"
    }
}

Device Information Update

Device information updates are sent from the Position Engine every minute to notify of changes to the iBeacon, Eddystone, battery level, and device identification data of the devices in a venue.

Format:

{
    "timestamp": "The time of the event in msecs since 1970, UTC",
    "eventType": "deviceInfoUpdate",
    "venueId": "The unique ID of the venue",
    "devices": [
        {
            "deviceId": "The unique ID of the device",
            "updated": "True if beacon information has been modified",
            "mV": "The battery level in millivolts",
            "eddystone": {
                "enabled": "True/False - No other attributes if False",
                "uid": "string of 32 hex characters",
                "url": "string properly formatted url"
            },
            "ibeacon": {
                "enabled": "True/False - No other attributes False",
                "uuid": "string of hex characters with dashes (eg. ce400000-c5a3-f393-c0a9-c50e24ccca9c)",
                "major": "integer 0-65535",
                "minor": "integer 0-65535"
            },
            "identification": {
                "model": "string",
                "manufacturer": "string",
                "softwareVersion": "string",
                "hardwareVersion": "string"
            }
        },
    ...
    ]
}

Authentication

apiKey

Security scheme type: API Key
header parameter name: x-api-key

HistoricalPositions

The Fathom platform stores the positions that it calculates for all devices. These historical positions can be retrieved through the following methods.

PostQuery

This method creates a query to retrieve the historical positions of beacons within the venue identified by the id parameter. The body of the post request should contain a QueryRequest in JSON format. The query operation may take some time to complete, so the response contains a 'state' attribute that indicates the state of the query. The state attribute value will be one of:

'SUCCEEDED', 'FAILED', 'QUEUED', 'RUNNING', 'CANCELLED'

The response of this operation contains an object with an id field that represents the query. This query id value can be passed to the getQueryResult operation to retrieve the current query state. Once the query state is 'SUCCEEDED', the value of the response 'url' attribute can be used to retrieve the results of the query.

Authorizations:
apiKey (:venueIdvenues)
path Parameters
id
required
string

The identifier for the venue.

Request Body schema: application/json
startDate
required
string

The start date in format YYYY-MM-DD (2018-12-22).

endDate
required
string

The end date in format format YYYY-MM-DD (2018-12-23).

venueId
string Nullable

The venue identifier. This field is optional if it is already defined in the request path.

deviceId
string Nullable

The device identifier. If not supplied, positions are returned for all devices in the venue.

registeredOnly
required
boolean

Optionally restrict the response to registered devices only.

Responses

200

Ok

post /historical-positions/query/venues/{id}
https://api.fathomsys.com/historical-positions/query/venues/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "startDate": "string",
  • "endDate": "string",
  • "venueId": "string",
  • "deviceId": "string",
  • "registeredOnly": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

GetQueryResult

This method retrieves the current state of a query represented by the supplied query identifier. The query Id is passed as a query parameter with name 'id'.

Authorizations:
apiKey (:venueIdvenues)
path Parameters
id
required
string

The identifier for the venue.

query Parameters
id
required
string

The query identifier.

Responses

200

Ok

get /historical-positions/query/venues/{id}/byQueryId
https://api.fathomsys.com/historical-positions/query/venues/{id}/byQueryId

Response samples

application/json
Copy
Expand all Collapse all
{}

Hubs

Fathom hubs are devices that are installed within a venue to detect the position of bluetooth beacons. These methods allow querying and configuration of the Fathom hubs.

GetHubsByVenue

This method retrieves information about the hubs in the specified venue.

Authorizations:
apiKey (?idvenues)
query Parameters
id
required
string

The identifier of the venue to query for hubs.

continuationToken
string

If there are too many hubs to return in a single response, the response will contain a continuationToken. The continuationToken can be passed to subsequent requests to return the next set of hubs.

page
string

Control pagination. Set page size with page[size]=number.

Responses

200

Ok

get /hubs/byVenueId
https://api.fathomsys.com/hubs/byVenueId

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

GetHub

This method retrieves information about the hub identified by the hub id.

Authorizations:
apiKey (:id)
path Parameters
id
required
string

The identifier of the hub.

Responses

200

Ok

get /hubs/{id}
https://api.fathomsys.com/hubs/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

PutHub

This method replaces all properties of the specified hub.

Authorizations:
apiKey (:id)
path Parameters
id
required
string

The identifier of the hub.

Request Body schema: application/json
links
object (Link)
included
Array of object (ResourceObject) Nullable

an array of resource objects that are related to the primary data and/or each other (“included resources”).

meta
object Nullable

a meta object that contains non-standard meta-information.

data
required
object (GenericResourceObjectHubInputAttributes)

Responses

200

Ok

put /hubs/{id}
https://api.fathomsys.com/hubs/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "links":
    {
    },
  • "included":
    [
    ],
  • "meta": { },
  • "data":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

DeleteHub

This method deletes the hub identified by the hub id.

Authorizations:
apiKey (:id)
path Parameters
id
required
string

The identifier of the hub.

Responses

200

Ok

delete /hubs/{id}
https://api.fathomsys.com/hubs/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

PatchHub

This method replaces a subset of properties of the specified hub.

Authorizations:
apiKey (:id)
path Parameters
id
required
string

The identifier of the hub.

Request Body schema: application/json
links
object (Link)
included
Array of object (ResourceObject) Nullable

an array of resource objects that are related to the primary data and/or each other (“included resources”).

meta
object Nullable

a meta object that contains non-standard meta-information.

data
required
object (GenericResourceObjectHubInputAttributes)

Responses

200

Ok

patch /hubs/{id}
https://api.fathomsys.com/hubs/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "links":
    {
    },
  • "included":
    [
    ],
  • "meta": { },
  • "data":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Identities

Fathom identities are used to identity users of the Fathom API and User Interface. Identities have associated API keys and roles.

CreateIdentity

This method creates an identity for the purpose of accessing the Fathom API.

Authorizations:
Request Body schema: application/json
links
object (Link)
included