TLC V2 Protocol Traxmate

The Traxmate Location Controller is Traxmate’s fast and always online data parser and location provider. It supports several protocols, with more continually being developed. The most commonly used protocol is the v2 protocol on this page, which is versatile and can be applied to various use cases.

Request Parameters #

Only the servicetoken (API key) is required for a successful post. Id and nr are both optional parameters.

Parameter	Required	Type	Description
servicetoken	true	string	The unique token, identifier, for the account, received from Traxmate.
id	false	string	A unique device id. Used for per-device plans and outlier filtering. Important to be truly unique for the account, otherwise requests may not receive correct position. Max 20 characters in length.
nr	false	integer	Request number set by the device. First request should have 1 and then value should be increased by 1 for each request. Helps to identify correct response to a request if a delay in network or lookup.

Request Body #

Depending on your device’s capabilities and use case, you can select to send many different types of sensor data and settings. If your device has GPS, it’s advised to always include it.

Positioning Information #

Parameter	Required	Type	Description
cellTowers	false	array	An array of all cell towers. There is no limit on the number of towers; send as many as possible.
wifiAccessPoints	false	array	An array of wifi access points (APs). There is no limit on the number of APs; send as many as possible.
bluetoothBeacons	false	array	An array of bluetooth beacons. There is no limit on the number of beacons; send as many as possible.
gps	false	array	Latest GPS information. Improves positioning requests with latest GPS position, for example, indoors where the latest GPS position is normally at the door of the building. If GPS position is older than 600s, it does not add any value and should be omitted. GPS object is also used for contributing to the database if age=0 and there is at least one cell or one wifi included. Contributions are not calculated as successful requests.
fallbacks	false	object	Fallback solutions. The request will check different fallback solutions to create a position if none of the submitted cells or wifis are found. These parameters should be used with care since they could potentially return wrong coordinates.

Advanced Positioning Information #

Parameter	Required	Type	Values	Description
sensors	false	array		An array of sensor parameters to improve positioning accuracy.

Address Information #

Parameter	Required	Type	Values	Default	Description
geoname	false	integer	0..1	0	Request name of location. Disregarded if omitted or 0. If set to 1, the city, country, and country code information will be returned in the geoname parameter array in the response.
address	false	integer	0..1	Depending on key setting	If set to 1, a reverse geocode lookup will be made on the calculated location. If successful, the address information will be returned in the response. A successful response will count as an extra request.
indoor	false	integer	0..1	Depending on key setting	Ask for indoor information in the response. If information is found and provided, it will be counted as an extra request.

Fallback Parameters #

These parameters should be used carefully since they could potentially return wrong coordinates. An associative array with values 1 for on and 0 for off. Parameters for turning individual fallbacks on or off:

Parameter	Required	Type	Values	Description
all	false	integer	0..1	Enable/disable all fallbacks for this request. (This does not include cidxf which has to be activated manually.)
w4f	false	integer	0..1	Used to support mobile units only able to read 4 CID Hex digits of a WCDMA CID (normally 8

Successful response #

A Successful Geolocation Request #

A successful geolocation request will return a JSON-formatted response defining a location and radius.

The request returns a JSON like this:

{
    "accuracy": 500,
    "location": {
        "lat": 59.331706,
        "lng": 18.079073
    },
    "logId": 1237798
}

A state variable is returned if (indoors or speed filter is set on the key) and (an id is set). Include this state variable in the next request to improve accuracy and enable the speed filter:

{
    "accuracy": 500,
    "location": {
        "lat": 59.331706,
        "lng": 18.079073
    },
    "state": "eyJvcyI6MCwiZmkiOjAsmxyIjpbeyJhY2N1cmFjeSI6NTAwLCJsb2NhdGlvbiI6eyJsYXQiOjU5LjMzMTcwNiwibG5nIjoxOC4wNzkwNzN9LCJ0aW1lc3RhbXAiOjE2MDIyNTA4ODMsImdlb25hbWUiOnsidG93biI6IlN0b2NraG9sbSIsImNvdW50cnkiOiJTd2VkZW4iLCJjb3VudHJ5X2NvZGUiOiJTRSJ9fV19",
    "logId": 9265772
}

Response Parameters #

Parameter	Type	Description
location	array	Array of the estimated location. See below for details.
accuracy	integer	The accuracy is the estimated median error in meters, i.e. the radius in a circle with 50% confidence level.
heading	decimal	Heading for GPS location if available.
altitude	decimal	Altitude for GPS location if available.
speed	decimal	Speed for GPS location if available (m/s).
calculatedSpeed	integer	Calculated speed between this and previous location (m/s).
geoname	array	If geoname is set in the request, the geoname object will be returned if available. See below for details.
indoor	array	If indoor is set in the request, the indoor object will be returned if available. See below for details.
address	array	If address is set in the request, the address object will be returned if available. See the Reverse Geocoding section for an example of possible address fields.
fallback	string	If this field is included, no direct match was found. It shows which fallback was used to generate the response.
state	string	If this field is included, it should preferably be used in the next request for the specific device. The parameter includes positioning history that enhances indoor positioning performance and enables speed filter.
logId	integer	A logId of the request that could be used for debugging purposes. Requests are stored for a maximum of 7 days currently and can be downloaded in the portal.

Location #

The location object contains the following fields.

Parameter	Type	Description
lat	decimal	The latitude of the estimated location.
lng	decimal	The longitude of the estimated location.

Geoname #

The geoname object can contain the following fields.

Parameter	Type	Description
town	string	Town of the location.
country	string	Country of the location.
country_code	string	Country code of the location according to ISO 3166.

Indoor #

The indoor object can contain the following fields.

Parameter	Type	Description
buildingModelId	integer	The ID of the building model used to calculate the location.
buildingId	integer	The ID of the building that the used building model belongs to.
building	string	The name of the building that the used building model belongs to.
floorIndex	integer	The index of the calculated floor if available. 0 means ground level.
floorLabel	string	The name of the calculated floor if available.
room	string	The name of the calculated room if available.

API Examples #

Sample Request for Positioning with NR (5G) #


curl "https://gw.traxmate.io/v2/d4f4c920-4e3a-11eb-8d0e-6f5d5d8d7d3e"
 
    -X POST                                
    -H "Content-Type: application/json"    
    -d '{
    "radioType": "nr",
    "cellTowers": [{
        "mobileCountryCode": 240,
        "mobileNetworkCode": 1,
        "locationAreaCode": 77,
        "cellId": 2147483647
    }]
}

Cell Parameters #

GSM Cells (2G, GSM, EDGE, GPRS) #

Parameter	Required	Type	Values	Description
radioType	recommended	string	gsm	The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode	true	integer	0..999	The Mobile Country Code (MCC).
mobileNetworkCode	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	true	integer	0..65535	The Location Area Code (LAC).
cellId	true	integer	0..65535	The Cell ID (CID).
signalStrength	recommended	integer	-120–25	The measured signal strength for this cell tower in dBm.
timingAdvance	false	integer	0..63	The timing advance value for this cell tower when available.
serving	false	integer	0..1	Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

CDMA Cells (CDMA, 1xRTT, EVDO) #

Parameter	Required	Type	Values	Description
radioType	recommended	string	cdma	The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode	false	integer	0..999	The Mobile Country Code (MCC).
mobileNetworkCode	true	integer	0..32767	The SystemID (SID).
locationAreaCode	recommended	integer	0..65535	The Network ID (NID).
cellId	true	integer	0..65535	The Basestation ID (BID).
signalStrength	recommended	integer	-120–25	The measured signal strength for this cell tower in dBm.
serving	false	integer	0..1	Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

WCDMA Cells (3G, WCDMA, UMTS, HSPA, HSDPA) #

Parameter	Required	Type	Values	Description
radioType	recommended	string	wcdma	The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode	true	integer	0..999	The Mobile Country Code (MCC).
mobileNetworkCode	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	recommended	integer	0..65535	The Location Area Code (LAC).
cellId	true	integer	0..268435455	The Cell ID (CID). Required at least once in a request including neighbouring cells.
signalStrength	recommended	integer	-130–25	The measured signal strength for this cell tower in dBm.
primaryScramblingCode	recommended	integer	0..511	The primary scrambling code for WCDMA and physical CellId for LTE.
serving	false	integer	0..1	Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

LTE Cells (4G, LTE, CAT-M1, CAT-M2, LTE-M) #

Parameter	Required	Type	Values	Description
radioType	recommended	string	lte	The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode	true	integer	0..999	The Mobile Country Code (MCC).
mobileNetworkCode	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	recommended	integer	0..65535	The Location Area Code (LAC).
cellId	true	integer	0..268435455	The Cell ID (CID). Required at least once in a request including neighbouring cells.
signalStrength	recommended	integer	-140–25	The measured signal strength for this cell tower in dBm.
primaryScramblingCode	recommended	integer	0..511	The primary scrambling code for WCDMA and physical CellId for LTE.
serving	false	integer	0..1	Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

NB-IoT Cells (NB-IoT, CAT-NB1, CAT-NB2)#

Parameter	Required	Type	Values	Description
radioType	recommended	string	nbiot	The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode	true	integer	0..999	The Mobile Country Code (MCC).
mobileNetworkCode	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	recommended	integer	0..65535	The Location Area Code (LAC).
cellId	true	integer	0..268435455	The Cell ID (CID). Required at least once in a request including neighbouring cells.
signalStrength	recommended	integer	-140–25	The measured signal strength for this cell tower in dBm.
primaryScramblingCode	recommended	integer	0..511	The primary scrambling code for WCDMA and physical CellId for LTE.
serving	false	integer	0..1	Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

NR Cells (5G, New Radio) #

Parameter	Required	Type	Values	Description
radioType	recommended	string	nr	The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode	true	integer	0..999	The Mobile Country Code (MCC).
mobileNetworkCode	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	recommended	integer	0..65535	The Location Area Code (LAC).
cellId/newRadioCellId	true	integer	0..68719476735	The Cell ID (CID). Required at least once in a request including neighbouring cells.
signalStrength	recommended	integer	-140–25	The measured signal strength for this cell tower in dBm.
primaryScramblingCode	recommended	integer	0..1023	The primary scrambling code for WCDMA and physical CellId for LTE.
serving	false	integer	0..1	Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

WiFi and Bluetooth Parameters #

WiFi Parameters #

NOTE: For privacy issues, at least 2 wifi access points must be submitted in a query to get a location.

Parameter	Required	Type	Values	Description
macAddress	true	string		The mac address also called BSSID of the Wifi router.
ssid	recommended	string		The SSID of the Wifi router.
ssidHex	recommended	string		The SSID of the Wifi network in a hex string format. Each byte of the SSID is represented by two HEX characters.
signalStrength	recommended	integer	-100–20	The measured signal strength for the access point in dBm.
frequency	false	integer		The frequency of the WiFi access point in MHz. Improves indoor location accuracy.
channel	false	integer		The channel measured of the WiFi access point.
age	false	string		Time ago the measurement was made in ms.

Bluetooth Parameters #

A sample request for positioning with iBeacon UUID, major, and minor:

curl "https://apiv2.combain.com?key=YOUR_API_KEY&id=12345678" \
    -X POST                                \
    -H "Content-Type: application/json"    \
    -d '{
  "bluetoothBeacons": [
    {
      "uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 253,
      "minor": 7435,
      "signalStrength": -80
    },
    {
      "uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 253,
      "minor": 7438,
      "signalStrength": -80
    }
  ]
}'

There are 2 ways to identify Bluetooth beacons for positioning: macAddress or for iBeacons: UUID, major, minor

Parameter	Required	Type	Values	Description
macAddress	true	string		The mac address of the Bluetooth beacon.
name	recommended	string		The name of the Bluetooth beacon.
signalStrength	recommended	integer	-100–20	The measured signal strength for the Bluetooth beacon in dBm.
age	false	string		Time ago the measurement was made in ms.
uuid	false	string		The uuid identifier of the beacon if iBeacon.
major	false	integer	0..65535	The major identifier of the beacon if iBeacon.
minor	false	integer	0..65535	The minor identifier of the beacon if iBeacon.

GPS and Sensor Parameters #

GPS Parameters #

If available, the latest GPS information improves positioning requests. For example, indoors, the latest GPS position is normally at the building’s door.
If the GPS position is older than 600s, it adds no value and should be omitted.
If age=0 and at least one cell or Wi-Fi are included, the GPS object is also used to contribute to the database.
Contributions are not calculated as successful requests.
Note: To be able to contribute for credits, your data has to be qualified. Contact support@combain.com to be a qualified data provider and receive free credits.

Parameter	Required	Type	Values	Description
latitude	true	decimal	-90..90	The GPS latitude.
longitude	true	decimal	-180..180	The GPS longitude.
accuracy	true	integer	0..255	The GPS accuracy (horizontal, CEP = 50%) in meters.
sat	recommended	integer	0..20	The number of satellites seen in the measurement.
age	recommended	integer	0..600	The age of the GPS location (in seconds).
altitude	recommended	integer	-1000..10000	The altitude of the GPS location.
altitudeAccuracy	false	integer	0..100	The accuracy of the altitude in meters for the GPS location.
heading	recommended	integer	0..360	The direction (bearing) of movement for the GPS location in degrees.
speed	recommended	integer	0..100	The speed of the GPS location in m/s.

LastLocation Parameters #

Used to send a previously known location of the devices for speed filtering.

Parameter	Required	Type	Values	Description
lat	true	decimal	-90..90	The last known latitude.
lng	true	decimal	-180..180	The last known longitude.
accuracy	true	integer	0..255	The accuracy of last known location in meters.
timestamp	true	integer/string	timestamp/date	Unix timestamp or date in RFC3339/ISO8601 format, for example “2006-01-02T15:04:05Z”.

Sensor Parameters #

These parameters are only used in indoor positioning mode with continuous tracking mode (max every 5s). Contact Combain support for details.

Error Codes #

The Traxmate TLC uses the error codes in the table below. In case you are posting in JSON-format the controller will return both error code and the error explanation.

Error Code	Meaning
400	Bad Request — Your request is invalid. Parse error or invalid key.
403	Forbidden — Out of credits!
404	Not Found — The location could not be found.
500	Internal Server Error — What did you do!?

Errors #

In the case of an error, a standard-format error response body will be returned, and the HTTP status code will be set to an error status.

The response contains an object with a single error object:

Parameter	Type	Description
error	array	Error element.
errors	array	All the errors that occurred.
domain	string	The domain of this error.
reason	string	The type of error.
message	string	The message for this error.
code	integer	Error code. 400 = Parse Error / Invalid key. 403 = Out of credits. 404 = Not found. 500 = Internal Server Error
message	string	The error message.
logId	integer	A logId of the request that could be used for debugging purposes. Requests are stored for maximum 7 days currently and can be downloaded in portal.

Knowledgebase

Getting started

Guides

Features

Whitepapers

Developer

API

TLC V2 Protocol

Request Parameters #

Request Body #

Positioning Information #

Advanced Positioning Information #

Address Information #

Fallback Parameters #

Successful response #

A Successful Geolocation Request #

Response Parameters #

Location #

Geoname #

Indoor #

API Examples #

Sample Request for Positioning with NR (5G) #

Cell Parameters #

GSM Cells (2G, GSM, EDGE, GPRS) #

CDMA Cells (CDMA, 1xRTT, EVDO) #

WCDMA Cells (3G, WCDMA, UMTS, HSPA, HSDPA) #

LTE Cells (4G, LTE, CAT-M1, CAT-M2, LTE-M) #

NB-IoT Cells (NB-IoT, CAT-NB1, CAT-NB2)#

NR Cells (5G, New Radio) #

WiFi and Bluetooth Parameters #

WiFi Parameters #

Bluetooth Parameters #

GPS and Sensor Parameters #

GPS Parameters #

LastLocation Parameters #

Sensor Parameters #

Error Codes #

Errors #

Did this article help you?

Knowledgebase

TLC V2 Protocol​

Request Parameters #

Request Body #

Positioning Information #

Advanced Positioning Information #

Address Information #

Fallback Parameters #

Successful response #

A Successful Geolocation Request #

Response Parameters #

Location #

Geoname #

Indoor #

API Examples #

Sample Request for Positioning with NR (5G) #

Cell Parameters #

GSM Cells (2G, GSM, EDGE, GPRS) #

CDMA Cells (CDMA, 1xRTT, EVDO) #

WCDMA Cells (3G, WCDMA, UMTS, HSPA, HSDPA) #

LTE Cells (4G, LTE, CAT-M1, CAT-M2, LTE-M) #

NB-IoT Cells (NB-IoT, CAT-NB1, CAT-NB2)#

NR Cells (5G, New Radio) #

WiFi and Bluetooth Parameters #

WiFi Parameters #

Bluetooth Parameters #

GPS and Sensor Parameters #

GPS Parameters #

LastLocation Parameters #

Sensor Parameters #

Error Codes #

Errors #

Did this article help you?

TLC V2 Protocol