JSON

Types#

OwnTracks uses JSON format for its message payloads. The different payload types are identified by a mandatory _type element. Depending on the app platform, different payload types are supported.

`_type`	iOS	Android
`beacon`	Y	N
`card`	Y	Y
`cmd`	Y	Y
`configuration`	Y	Y
`encrypted`	Y	Y
`location`	Y	Y
`lwt`	Y	Y
`request`	Y	N
`steps`	Y	N
`transition`	Y	Y
`waypoint`	Y	Y
`waypoints`	Y	Y

Topics#

In MQTT mode the apps publish to:

owntracks/user/device with _type=location for location updates, and with _type=lwt
owntracks/user/device/cmd with _type=cmd for remote commands
owntracks/user/device/event with _type=transition for enter/leave events
owntracks/user/device/step to report step counter
owntracks/user/device/beacon for beacon ranging
owntracks/user/device/dump for config dumps
owntracks/user/device/waypoint when a geofence is created on the device
owntracks/user/device/waypoints (plural) when exporting a list of configured waypoints from device to backend

In MQTT mode apps subscribe to:

owntracks/user/device/cmd if remote commands are enabled
owntracks/+/+ for seeing other user's locations, depending on broker ACL
owntracks/+/+/event for transition messages (enter/leave)
owntracks/+/+/info for obtaining cards.

In HTTP mode the apps POST their data to a single endpoint you configure.

`_type=location`#

This location object describes the location of the device that reported it.

{
    "_type" : "location",
    elements
}

acc Accuracy of the reported location in meters without unit (iOS,Android/integer/meters/optional)
alt Altitude measured above sea level (iOS,Android/integer/meters/optional)
batt Device battery level (iOS,Android/integer/percent/optional)
bs Battery Status 0=unknown, 1=unplugged, 2=charging, 3=full (iOS, Android)
cog Course over ground (iOS/integer/degree/optional)
lat latitude (iOS,Android/float/degree/required)
lon longitude (iOS,Android/float/degree/required)
rad radius around the region when entering/leaving (iOS/integer/meters/optional)
t trigger for the location report (iOS,Android/string/optional)
- p ping issued randomly by background task (iOS,Android)
- c circular region enter/leave event (iOS,Android)
- C circular region enter/leave event for +follow regions (iOS)
- b beacon region enter/leave event (iOS)
- r response to a reportLocation cmd message (iOS,Android)
- u manual publish requested by the user (iOS,Android)
- t timer based publish in move move (iOS)
- v updated by Settings/Privacy/Locations Services/System Services/Frequent Locations monitoring (iOS)
tid Tracker ID used to display the initials of a user (iOS,Android/string/optional) required for http mode
tst UNIX epoch timestamp in seconds of the location fix (iOS,Android/integer/epoch/required)
vac vertical accuracy of the alt element (iOS/integer/meters/optional)
vel velocity (iOS,Android/integer/kmh/optional)
p barometric pressure (iOS/float/kPa/optional/extended data)
poi point of interest name (iOS/string/optional)
conn Internet connectivity status (route to host) when the message is created (iOS,Android/string/optional/extended data)
- w phone is connected to a WiFi connection (iOS,Android)
- o phone is offline (iOS,Android)
- m mobile data (iOS,Android)
tag name of the tag (iOS/string/optional)
topic (only in HTTP payloads) contains the original publish topic (e.g. owntracks/jane/phone). (iOS,Android >= 2.4,string)
inregions contains a list of regions the device is currently in (e.g. ["Home","Garage"]). Might be empty. (iOS,Android/list of strings/optional)
inrids contains a list of region IDs the device is currently in (e.g. ["6da9cf","3defa7"]). Might be empty. (iOS,Android/list of strings/optional)
SSID, if available, is the unique name of the WLAN. (iOS,string/optional)
BSSID, if available, identifies the access point. (iOS,string/optional)
created_at identifies the time at which the message is constructed (vs. tst which is the timestamp of the GPS fix) (iOS,Android)
m identifies the monitoring mode at which the message is constructed (significant=1, move=2) (iOS/integer/optional)
_id random identifier to be used by consumers to correlate & distinguish send/return messages (Android/string)

Notes#

The tst in a ping is a current timestamp, so that it doesn't look like a duplicate.
The tid defaults to the last two characters of the topic
A missing t element also indicates an automatic location update
A publish of "_type": "location" with a "b" trigger is sent when an iOS device enters or leaves a beacon in addition to a "_type": "transition": if somebody leaves and enters his home without having left the radius of detection for significant changes, a subscriber to his main topic would otherwise not get notified of any location change although beacon or circular region enter and leave transitions were generated.
The acc, alt, cog, vac, vel elements are only added if they are not zero
Some Android devices always return 0 for alt or vel
Elements marked with extended data are only added if extendedData=true is configured
Android devices using a VPN might not report either of SSID/BSSID which might be expected behaviour. #1888

Queclink#

OwnTracks works with a selection of trackers by Queclink, for which the protocol conversion is done via qtripp. Queclink devices report the following additional elements in a _type=location message:

{
    "_type": "location",
    elements
}

t trigger for the location report (string/optional)
- o Corner
- M Mileage
- ! Tow or fake tow or sensor without ignition
- a motionless (aka park)
- i ignition on
- I ignition off
- e external power off
- E external power ON
- 1 Devices powered up
- 2 Battery stop charging
- 3 Battery start charging
- 9 Battery power low
- h harsh behavior
- s speed alarm
odometer total distance of the device (float/kilometers/optional)
hmc total hours of operation (float/seconds/optional)
ubatt voltage of the battery (float/volts/optional)
uext voltage of the external power source (float/volts/optional)
vin vehicle identification number (string/optional)
imei identification number (string/optional)
name vehicle name (string/optional)
don is duration since ignition on (float/seconds/optional)
doff is duration since ignition off (float/seconds/optional)
aiv is analog input voltage (float/volts/optional)
rpm is engine rounds per minute (float/rounds per minute/optional)
fcon is fuel consumption (float/L per 100km/optional)
flvl is fuel level (float/percent/optional)
anum is number of analog inputs (integer/optional)
adid-xx is id of analog input number xx (string/optional)
adty-xx is type of analog input number xx (string/optional)
adda-xx is data of analog input number xx (string/optional)
temp_c-xx is temperature of analog input number xx (float/celsius/optional)
can is can data (string/optional)
din1 is status of digital input 1 (boolean/optional)
din2 is status of digital input 2 (boolean/optional)
dout1 is status of digital output 1 (boolean/optional)
dout2 is status of digital output 2 (boolean/optional)
ign is status of ignition (boolean/optional)
motion is motion status (boolean/optional)
tow is status of tow sensor (boolean/optional)
fake is status of fake tow sensor (boolean/optional)
sens is status of motion sensor (boolean/optional)
sent is epoch when message was sent (integer/epoch/optional)
mcc is mobile country code (integer/optional)
mnc is mobile network code (integer/optional)
lac is location area code (string/optional)
cid is cell id (string/optional)
nmds is non movement detection status (boolean/optional)
rit queclink record id and type (integer/optional)
rty queclink record type (integer/optional)
rid queclink record id (integer/optional)
mst queclink motion state (integer/optional)
count is counter of message (string/optional)
raw_line raw data (string/optional)
counter number of ignored positions (integer/optional)
ignored indicates counter positions have been ignored (boolean/optional)

Notes#

The device can be configured to produce or not produce fields marked as optional

`_type=lwt`#

A last will and testament is published automatically by the MQTT broker when it loses contact with the app. This typically looks like this:

{
    "_type":"lwt",
    elements
}

tst UNIX epoch timestamp at which the app first connected (iOS,Android/integer/epoch/required)

`_type=waypoint`#

Waypoints / regions denote specific geographical regions that you want to keep track of. You define a region in the OwnTracks app, and OwnTracks publishes this waypoint to the topic branch ../waypoint (singular). OwnTracks also monitors these waypoints and will publish {_type: "transition", ...} message when entering or leaving the region. A waypoint may also define a BLE Beacon instead of a geographical region.

{
    "_type"  : "waypoint",
    elements
}

desc Name of the waypoint that is included in the sent transition message, copied into the location message inregions array when a current position is within a region. (iOS,Android,string/required)
lat Latitude (iOS,Android/float/meters/optional)
lon Longitude (iOS,Android/float/meters/optional)
rad Radius around the latitude and longitude coordinates (iOS,Android/integer/meters/optional)
tst Timestamp of creation of region, copied into the wtst element of the transition message (iOS,Android/integer/epoch/required)
uuid UUID of the BLE Beacon (iOS/string/optional)
major Major number of the BLE Beacon (iOS/integer/optional)
minor Minor number of the BLE Beacon_(iOS/integer/optional)_
rid region ID, created automatically, copied into the location payload inrids array (iOS/string)_

Notes#

In iOS version >= 9.1.0 the last three elements (uuid, major, and minor) are used to configure Beacon waypoints instead of encoding these values into the desc element.
If lat, lon and rad elements are present, transition messages are sent when entering and leaving the geographical region
If uuid, major, minor elements are present, BLE becons with that specifications are monitored
Beacons and Geographical regions can be defined together
Waypoint messages are published non-retained because the second waypoint would overwrite the first: a client would only get the last one which makes no sense. Your application will typically store waypoints to some kind of persistent storage.
Waypoints are sent to the broker and transition messages contain a desc and event element.

`_type=transition`#

A transition message is sent, when entering or leaving a previously configured geographical region or BLE Beacon. In addition to the coordinates where the event fired, the message contains the timestamp of the waypoint creation as well as the event that triggered the transition message with its description. MQTT transition messages are published non retained.

{
    "_type": "transition",
    elements
}

wtst Timestamp of waypoint creation (iOS,Android/integer/epoch/required)
lat Latitude at which the event occured (iOS,Android/float/meters/optional)
lon Longitue at which the event occured (iOS,Android/float/meters/optional)
tst Timestamp at which the event occured (iOS,Android/integer/epoch/required)
acc Accuracy of the geographical coordinates (iOS,Android/int/meters/required)
tid Tracker ID of the (iOS/string/none/optional) required in http mode.
event Event that triggered the transition (iOS,Android/string/required)
- enter The device entered the defined geographical region or BLE Beacon range (iOS)
- leave The device left the defined geographical region or BLE Beacon range (iOS)
desc Name of the waypoint (iOS,Android/string/optional)
t Trigger of the event (iOS,Android/string/optional)
- c Circular geographical region (iOS, Android)
- b BLE Beacon (iOS)
- l Location update (Android)
rid Region ID (iOS/Android, after January 2021)

`_type=configuration`#

The device configuration can be imported and exported as JSON. The exported configuration can contain an array of waypoints that are defined on the device. If enabled, apps also accept remote configuration messages.

{
    "_type": "configuration",
    elements
}

allowRemoteLocation Respond to reportLocation cmd message (iOS/boolean)
allowinvalidcerts disable TLS certificate checks insecure (iOS/boolean)
auth Use username and password for endpoint authentication (iOS,Android/boolean)
autostartOnBoot Autostart the app on device boot (Android/boolean)
cleanSession MQTT endpoint clean session (iOS,Android/boolean)
clientId client id to use for MQTT connect. Defaults to "user deviceId" (iOS,Android/string)
clientpkcs Name of the client pkcs12 file (iOS/string)
cmd Respond to cmd messages (iOS,Android/boolean)
connectionTimeoutSeconds (default 30) TCP timeout for establishing a connection to the MQTT / HTTP broker, (Android/int)
debugLog (default false) whether or not debug logs should be shown in the log viewer / exporter activity (Android/bool)
deviceId id of the device used for pubTopicBase and clientId construction. Defaults to the os name of the device (iOS,Android/string)
downgrade battery level below which to downgrade monitoring from move mode (iOS/integer/percent/optional)
encryptionKey the secret key used for payload encryption (iOS,Android/string)
extendedData Add extended data attributes to location messages (iOS,Android/boolean)
host MQTT endpoint host (iOS,Android/string)
httpHeaders extra HTTP headers:field names and field content are separated by a colon (:), multiple fields by a backslash-n (\n) \<field-name>:\<field-content>\n\<field-name>:\<field-content>... (iOS only/string)
ignoreInaccurateLocations Location accuracy below which reports are supressed (iOS,Android/integer/meters)
ignoreStaleLocations Number of days after which location updates are assumed stale. Locations sent by friends older than the number of days specified here will not be shown on map or in friends list. Defaults to 0, which means stale locations are not filtered. (iOS,Android/integer/days)
keepalive MQTT endpoint keepalive (iOS,Android/integer/seconds)
locatorDisplacement maximum distance between location source updates (iOS,Android/integer/meters)
locatorInterval maximum interval between location source updates (iOS,Android/integer/seconds)
locatorPriority source/power setting for location updates (Android/integer)
- 0 NO_POWER / best accuracy possible with zero additional power consumption (Android)
- 1 LOW_POWER / city level accuracy (Android)
- 2 BALANCED_POWER / block level accuracy based on Wifi/Cell (Android)
- 3 HIGH_POWER / most accurate accuracy based on GPS (Android)
locked Locks settings screen on device for editing (iOS/boolean)
maxHistory Number of notifications to store historically. Zero (0) means no notifications are stored and history tab is hidden. Defaults to zero. (iOS/integer)
mode Endpoint protocol mode (iOS,Android/integer)
- 0 MQTT (iOS, Android)
- 3 HTTP (iOS, Android)
monitoring Location reporting mode (iOS,Android/integer)
- -1 Quiet
- 0 Manual
- 1 Significant
- 2 Move
mqttProtocolLevel MQTT broker protocol level (iOS,Android/integer)
- 3 MQTT 3 (default)
- 4 MQTT 3.1.1
- 5 MQTT 5 (iOS only)
notificationLocation Show last reported location in ongoing notification (Android/boolean)
opencageApiKey API key for alternate Geocoding provider. See OpenCage for details. (Android/string)
osmTemplate URL template for alternate tile provider. Defaults to https://tile.openstreetmap.org/{z}/{x}/{y}.png. (iOS/string)
osmCopyright Attribution text shown with OSM map. Defaults to (c) OpenStreetMap contributors. (iOS/string)
passphrase Passphrase of the client pkcs12 file (iOS/string)
password Endpoint password (iOS,Android/string)
pegLocatorFastestIntervalToInterval (default false) - if true, requests that that the device provide locations no faster than the specified interval. Location providers often use the requested interval as a "at least every" setting, and may return locations more frequencly. Some people wanted the behaviour where it also meant "no more frequently than", so this setting lets them specify this (Android/bool)
ping Interval in which location messages of with t:p are reported (Android/integer)
port MQTT endpoint port (iOS,Android/integer)
positions Number of locations to keep and display (iOS/integer)
pubTopicBase MQTT topic base to which the app publishes; %u is replaced by the user name, %d by device (iOS,Android/string)
pubRetain MQTT retain flag for reported messages (iOS,Android/boolean)
pubQos MQTT QoS level for reported messages (iOS,Android/integer)
ranging Beacon ranging (iOS/boolean)
remoteConfiguration Allow remote configuration by sending a setConfiguration cmd message (Android/boolean)
sub subscribe to subTopic via MQTT (iOS,Android/boolean)
subTopic A whitespace separated list of MQTT topics to which the app subscribes if sub is true (defaults see topics) (iOS,Android/string)
subQos (iOS,Android/boolean)
tid Two digit Tracker ID used to display short name and default face of a user (iOS,Android/string)
tls MQTT endpoint TLS connection (iOS,Android/boolean)
tlsClientCrtPassword Passphrase of the client pkcs12 file (Android/string)
url HTTP endpoint URL to which messages are POSTed (iOS,Android/string)
username Endpoint username (iOS,Android/string)
ws use MQTT over Websocket, default false (iOS,Android/boolean)
waypoints Array of waypoint messages (iOS,Android/array)

Notes#

When importing a configuration message, all contained values are imported for the currently active mode. If the message also contains a mode element, the mode is changed first and all remaining elements are imported for the new mode.
In MQTT mode the server will consider the client as dead if it the keepalive interval plus 50% passed without receiving any MQTT packet from the client (e.g. after 90 sec if keepalive was 60). Afterwards, an lwt message will be send.

`_type=beacon`#

These messages are published when beacon ranging (iOS only) is enabled. Be advised that beacon ranging publishes a lot of messages and has a strong impact on battery life.

{
    "_type":"beacon",
    elements
}

desc name of the seen beacon (iOS/String)
uuid UUID of the seen beacon (iOS/String)
major Major number of the seen beacon (iOS/integer/epoch)
minor Minor number of the seen beacon (iOS/integer/epoch)
tst Timestamp at which the beacon was seen (iOS/integer/epoch)
acc Accuracy of the proximity value (iOS/integer/meters)
rssi Received signal strength of the beacon (iOS/integer/decibel)
proxRelative distance to the beacon (iOS/integer)
- 0 Proximity of the beacon could not be determined
- 1 Beacon is in the immediate vicinity
- 2 Beacon is relatively close to the user
- 3 Beacon is far away

Notes#

The theoretical relationship between RSSI and distance is RSSI[dbm] = −(10n log10(d) − A) where d is the distance and A is the offset which is the measured RSSI one meter point away from the beacon.

`_type=cmd`#

{"_type":"cmd", "action":"reportLocation"}
{"_type":"cmd", "action":"reportSteps"}
{"_type":"cmd", "action":"dump"}
{"_type":"cmd", "action":"status"}
{"_type":"cmd", "action":"waypoints"}
{"_type":"cmd", "action":"clearWaypoints"}
{"_type":"cmd", "action":"setConfiguration", "configuration":{"_type":"configuration",...}
{"_type":"cmd", "action":"setWaypoints", "waypoints":{"_type":"waypoints","waypoints":[...]}

action action to be performed by the device (iOS,Android/string)
- dump Triggers the publish of a configuration message (iOS)
- status Triggers the publish of a status message to ../status (iOS)
- reportSteps Triggers the report of a steps messages_(iOS)_
  - from Timestamp (iOS/epoch/optional)
  - to Timestamp (iOS/epoch/optional)
- reportLocation Triggers the publish of a location messages (iOS,Android) Don‘t expect device to be online. Send with QoS>0. Device will receive and repond when activated next time.
- clearWaypoints deletes all waypoints/regions (iOS)
- setWaypoints Imports (merge) and activates new waypoints (iOS,Android)
  - waypoints Array of waypoint messages to import (iOS,Android/array/required)
- setConfiguration Imports and activates new configuration values (iOS,Android)
  - configuration Configuration message to import (iOS,Android/required)
- waypoints Triggers publish of a waypoints message (iOS,Android)

Notes#

On iOS, the array of waypoints to the setWaypoints command allows updates / removal; the key of the waypoint is its name (desc). If you specify an invalid lat or lon (invalid means out of range number value e.g. -1000000, a string like "foo" will result in a 0 in app) the waypoint is deleted.
On Android there's a primary key which isn't surfaced to the API, and tst is a uniquely-constrained value which effectively acts like a key.

`_type=steps`#

{
    "_type":"steps",
    elements
}

tst Timestamp of the request (iOS/integer/epoch)
steps Steps walked with the device in the specfied time period (iOS/integer/steps)
from Effective start of time period (iOS/integer/epoch)
to Effective end of time period (iOS/integer/epoch)

Notes#

steps is -1 if device does not support step counting or specified time period is invalid

`_type=card`#

Apps read Card to display a name and icon for a user.

{
    "_type": "card",
    elements
}

name Name to identify a user (iOS,Android/string/optional)
face Base64 encoded PNG image that is displayed instead of the Tracker ID (iOS,Android/string/optional)

`_type=waypoints`#

The app can export a list of configured waypoints to the endpoint ../waypoints (plural).

{
    "_type": "waypoints",
    elements
}

_creator Identification of what created the array. Ignored by the apps (iOS,Android/string/optional)
waypoints Array of waypoint messages (iOS,Android/array/required)

`_type=encrypted`#

Apps can optionally encrypt outgoing messages with a shared symmetric key. The encrypted message is contained in the dataelement. For security reasons, the encryption key is not exported with configuration messages and cannot be imported.

{
    "_type": "encrypted",
    elements
}

data Encrypted and Base64 encoded original JSON message (iOS,Android/string/required)

`_type=request`#

Apps can request the creation of tours which elicit a cmd response from the Recorder. See tours for the details.

{
  "_type": "request",
  "request": "tour",
  "tour": {
    ...
  }
}

Types#

Topics#

_type=location#

Notes#

Queclink#

Notes#

_type=lwt#

_type=waypoint#

Notes#

_type=transition#

_type=configuration#

Notes#

_type=beacon#

Notes#

_type=cmd#

Notes#

_type=steps#

Notes#

_type=card#

_type=waypoints#

_type=encrypted#

_type=request#

`_type=location`#

`_type=lwt`#

`_type=waypoint`#

`_type=transition`#

`_type=configuration`#

`_type=beacon`#

`_type=cmd`#

`_type=steps`#

`_type=card`#

`_type=waypoints`#

`_type=encrypted`#

`_type=request`#