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. |