Overview

Benefit of TTS Open API, distributor or application vendor could provide tracking service to customers by calling the API and use your own GUI client, App or Website, this might improve the localization or user experience.

Your App or web client should connect to your application server, rather than connect to TTS API Server directly , use your application server connect to TTS Server instead.

Usage

1. Contact us to apply your appKey and appSecrect, you need to provide your account.
2. According to this document to implement your application server to obtain access_token.
3. Calling other interfaces with access_token to fulfil your business logic.

Conventions

Encoding, format & Timezone

UTF-8 and JSON is used by default.

Context-Type: default application/json charset=utf-8

The API use UTC (GMT +0)time in default: format yyyy-MM-dd HH:mm:ss

Common response fields

Result code description

Error code：

Work Flow

API Work Flow

API Features

API Description

Request URL

The unique request URL is:

https://openapi-tts-tracker.tanaka-tracker-system.jp/route/rest

Security

Client should get access_token first before calling the interface, which is generated by TTS Server by calling tts.oauth.token.get interface(method=tts.oauth.token.get) with provided appKey and appSecrect.

appKey and access_token are required to sign request parameters when calling API. TTS server will validate the the request parameters by checking the sign value.

Common Parameters

The parameters of each request should include common parameters and interface private parameters. For example, if you call the “tts.oauth.token.get” interface, you need to provide:

7(common parameters) + 3(private parameters) = 10 (parameters, key/value)

Following are the common parameters:

The parameter V uses a difference of 0.9 and 1.0:

• Using 0.9 will not perform Sign signature verification
• Using 1.0 will verify the Sign signature

Function description of Sign signature verification: The data receiving end gets the transmission text, but needs to confirm whether the text is the content sent by the sender, and whether it has been tampered with in the middle. Therefore, the receiver uses its own public key to decrypt the signature and obtains the digest of the text, then uses the same method as the sender to calculate the digest value of the text, and compares it with the decrypted digest, and finds that the two are exactly the same. It means that the text has not been tampered with.

Signature

To protect API calling from hacked, any API calling needs to be with a signature. TTS server will check signature based on request parameters. Illegal signature request will be rejected. Signature algorithms supported is: md5 (sign_method is a common parameter mentioned above).

Following is the algorithm of signature:

1. Sort all request parameters with parameter key in alphabetical order (including common parameters and method specific parameters, but NOT include sign and byte type parameter).
   
   For example:

   foo=1, bar=2, foo_bar=3, foobar=4

   Result:

   bar=2, foo=1, foo_bar=3, foobar=4

2. Remove all equal sign and comma:

   bar2foo1foo_bar3foobar4

3. Then concatenate appSecrect to the before and end of the result string and get the md5 value. E.g：

   md5(appSecrect+bar2foo1foo_bar3foobar4+appSecrect)

   like:

   md5(h9lri085eachcz4sn7gwnkh6j0jt0yz4bar2foo1foo_bar3foobar4h9lri085eachcz4sn7gwnkh6j0jt0yz4)

   Note that the string should be in UTF-8 encoding.
   Note that the sign should be upper case string.
4. If the parameter value is a byte stream, it should be converted to hexadecimal. For example:

   hex(“helloworld”.getBytes(“utf-8”)) = “68656C6C6F776F726C64”

MD5 is the 128-bit summary algorithm and is in hexadecimal. A hexadecimal character can represent four bits, so the signature string length is 32 hexadecimal characters.

JAVA example：
Algorithm

public static String signTopRequest(Map<String, String> params, String seccode, String signMethod) throws IOException {
    // 1: sort parameter key
    String[] keys = params.keySet().toArray(new String[0]);
    Arrays.sort(keys);

    // 2: put all parameter names and parameter values together
    StringBuilder query = new StringBuilder();
    if (Constants.SIGN_METHOD_MD5.equals(signMethod)) {
        query.append(seccode);
    }

    for (String key : keys) {
        String value = params.get(key);
        if (StringUtils.areNotEmpty(key, value)) {
            query.append(key).append(value);
        }
    }

    // 3: use MD5/HMAC to encrypt
    byte[] bytes;
    if (Constants.SIGN_METHOD_HMAC.equals(signMethod)) {
        bytes = encryptHMAC(query.toString(), seccode);
    } else {
        query.append(seccode);
        bytes = encryptMD5(query.toString());
    }

    // 4: convert binary to uppercase hexadecimal
    return byte2hex(bytes);
}

public static byte[] encryptHMAC(String data, String seccode) throws IOException {
    byte[] bytes = null;
    try {
        seccodeKey seccodeKey = new seccodeKeySpec(seccode.getBytes(Constants.CHARSET_UTF8), "HmacMD5");
        Mac mac = Mac.getInstance(seccodeKey.getAlgorithm());
        mac.init(seccodeKey);
        bytes = mac.doFinal(data.getBytes(Constants.CHARSET_UTF8));
    } catch (GeneralSecurityException gse) {
        throw new IOException(gse.toString());
    }
    return bytes;
}

public static byte[] encryptMD5(String data) throws IOException {
    return encryptMD5(data.getBytes(Constants.CHARSET_UTF8));
}

public static String byte2hex(byte[] bytes) {
    StringBuilder sign = new StringBuilder();
    for (int i = 0; i < bytes.length; i++) {
        String hex = Integer.toHexString(bytes[i] & 0xFF);
        if (hex.length() == 1) {
            sign.append("0");
        }
        sign.append(hex.toUpperCase());
    }
    return sign.toString();
}

Get Access Token

Description

Client(distributor’s server) should stored the access_token locally, do NOT get access_token per request, instead, use the local access_token before it become invalid. TTS server will not allow to access if the request frequency is too high from client.

The access token can be used for about 2 hours(depend on the value for expires_in parameter), do NOT try to get token for every request.

Request URL

See the unique request URL.
Method: tts.oauth.token.get

HTTP request method

POST

Request parameter

• （1）Common parameters
• （2）Private parameters as follow:

Response

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": {
    "appKey": "8FB345B8693CCD003CC2DAB61EC8791D",
    "account": "ttstest",
    "accessToken": "7da3330ec28e3996b6ef4a7e3390ba71",
    "expiresIn": 60,
    "refreshToken": "7da3330ec28e3996b6ef4a7e3390ba71",
    "time": "2017-06-15 10:00:00"
  }
}

Return error example:

{"code":xxx,"message":"Incorrect user name or password"}

Postman Demo

user_id = your account.
user_pwd_md5 = md5(your account password).
Sign = md5(<app_secrect>your alphabet ordered parameters keyvalue, without equal-sign, comma and not include sign field<app_secrect>).
Note that sign is a 32-length upper case string.

For example:

<app_secrect>app_key9FB345B8693CCD0054E44ADF99139409expires_in7200formatjsonmethodtts.oauth.token.getsign_methodmd5timestamp2017-09-28 01:55:00user_id<account>user_pwd_md5<password_md5>v1.0<app_secrect>

Refresh Access Token

Description

This interface is used to update token manually when access token is about to be invalid.

Request URL

See the unique request URL.
Method: tts.oauth.token.refresh

HTTP request method

POST

Request Parameters

• （1）Common parameters
• （2）Private parameters

Response

Example for correct Response:

{
  "code": 0,
  "message": "success",
  "result": {
    "appKey": "8FB345B8693CCD003CC2DAB61EC8791D",
    "account": "ttstest",
    "accessToken": "7da3330ec28e3996b6ef4a7e3390ba71",
    "expiresIn": 60,
    "refreshToken": "7da3330ec28e3996b6ef4a7e3390ba71",
    "time": "2017-06-15 10:00:00"
  }
}

Return error example:

{"code":xxx,"message":"Illegal request，token is invalid"}

List all sub-account

Description

List all sub-account of a specified account.

Request URL

See the unique request URL.
Method: tts.user.child.create

HTTP request method

POST

Request Parameters

• （1）Common parameters
• （2）Private parameters

Response

Result

Correct return example

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "account": "123123",
      "name": "test",
      "type": 8,
      "displayFlag": 1,
      "address": null,
      "birth": "2017-04-22 00:00:00",
      "companyName": "",
      "email": "",
      "phone": "",
      "language": "zh",
      "sex": 0,
      "enabledFlag": 1,
      "remark": null
    }
  ]
}

Wrong return example

{"code":xxx,"message":"The account does not exist"}

create sub-account

description

create a sub-account of a specified account.

Request URL

See the unique request URL.
Method: tts.user.child.create

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

response

Correct return example：

{
  "code": 0,
  "message": "Vehicle information modification successful",
  "result": null
}

Wrong return example：

{"code":xxx,"message":"The account does not exist"}

Remove sub-account

Description

Remove a sub-account of a specified account.

Request URL

See the unique request URL.
Method: tts.user.child.del

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

Response

Correct return example：

{
  "code": 0,
  "message": "Vehicle information modification successful",
  "result": null
}

Wrong return example：

{"code":xxx,"message":"no permissions"}

Move account

Description

Move account from one sub-account to another sub-account.

Request URL

See the unique request URL.
Method: tts.user.child.move

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

Response

Correct return example：

{
  "code": 0,
  "message": "Vehicle information modification successful",
  "result": null
}

Wrong return example：

{"code":xxx,"message":"no permissions"}

List all devices of sub-account

Description

Query all devices of a specified account.

Request URL

See the unique request URL.
Method: tts.user.device.list

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

Result：

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "imei": "868120145233604",
      "deviceName": "868120145233604",
      "mcType": "GT300L",
      "mcTypeUseScope": "personal",
      "sim": "415451",
      "expiration": "2037-04-01 23:59:59",
      "activationTime": "2017-04-01 11:02:20",
      "reMark": "test",
      "vehicleName": null,
      "vehicleIcon": "bus",
      "vehicleNumber": "粤B3604",
      "vehicleModels": null,
      "carFrame": "2235",
      "driverName": "driver",
      "driverPhone": "13825036579",
      "enabledFlag": 1,
      "engineNumber": "8565674",
      "deviceGroupId": "b54ab3c430864e31a64e54de44c79a1d",
      "deviceGroup": "default group"
    }
  ]
}

Return error example：

{"code":xxx,"message":"Account queried doesn’t exist"}

Get device detail information

Description

Get device detail information for specific IMEI.

Request URL

See the unique request URL.
Method: tts.track.device.detail

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

Result：

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": {
    "imei": "868120145233604",
    "deviceName": "868120145233604",
    "mcType": "GT300L",
    "mcTypeUseScope": "personal",
    "sim": "415451",
    "expiration": "2037-04-01 23:59:59",
    "activationTime": "2017-04-01 11:02:20",
    "reMark": "test",
    "vehicleName": null,
    "vehicleIcon": "bus",
    "vehicleNumber": "粤B3604",
    "vehicleModels": null,
    "carFrame": "2235",
    "driverName": "driver",
    "driverPhone": "13825036579",
    "enabledFlag": 1,
    "engineNumber": "8565674",
    "iccid": "xxxxxxx",
    "imsi": "xxxx",
    "importTime": "2017-04-01 11:02:20",
    "licensePlatNo": "8565674",
    "VIN": "xxxxxxx",
    "vehicleBrand": "xxxx",
    "fuel_100km": "9",
    "status": "8565674",
    "currentMileage": "102.5",
    "deviceGroupId": "b54ab3c430864e31a64e54de44c79a1d",
    "deviceGroup": "default group"
  }
}

Return error example：

{"code":xxx,"message":"Account queried doesn’t exist"}

Get location of devices by account

Description

Get the latest location for all devices under an account.

Request URL

See the unique request URL.
Method: tts.user.device.location.list

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

Response

Result data:

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "imei": "868120145233604",
      "deviceName": "868120145233604",
      "icon": "bus",
      "status": "0",
      "posType": "GPS",
      "lat": 22.577282,
      "lng": 113.916604,
      "hbTime": "2017-04-26 09:14:50",
      "accStatus": "0",
      "speed": "0",
      "gpsTime": "2017-04-26 09:17:46",
      "activationFlag": "1",
      "expireFlag": "1",
      "electQuantity": "60",
      "locDesc": null,
      "powerValue": null,
      "temperature": "86.5",
      "trackerOil": null
    }
  ]
}

Wrong return example：

{"code":xxx,"message":"The account does not exist"}

Get the location of device(s)

Description

Get the latest location for one or multiple devices.

Request URL

See the unique request URL.
Method: tts.device.location.get

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

Response

Result list：

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "imei": "868120145233604",
      "deviceName": "868120145233604",
      "icon": "bus",
      "status": "0",
      "posType": "GPS",
      "lat": 22.577282,
      "lng": 113.916604,
      "hbTime": "2017-04-26 09:14:50",
      "accStatus": "0",
      "speed": "0",
      "gpsNum": "11",
      "gpsTime": "2017-04-26 09:17:46",
      "activationFlag": "1",
      "expireFlag": "1",
      "electQuantity": "60",
      "locDesc": null,
      "powerValue": null,
      "temperature": "86.5",
      "trackerOil": null,
      "currentMileage": "86.5"
    }
  ]
}

Wrong return example：

{"code":xxx,"message":"Illegal device"}

Get sharing location URL

Description

Get the URL of device location showing on the Map.

Request URL

See the unique request URL.
Method: tts.device.location.URL.share

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

Response

result Object：

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": {
    "URL": "data.16180track.com/api/share?ver=2&method=trackDevice_abr&deviceinfo=7ae7c62385f2067f164002db315854a969a40e3888021cb01dc8f2183ca08dbbd8581f6bb86df4c2e3e1b887cb67c21039b4c0ced18fdf8dd08e0460c5edd13ad87e16dca9702ce6"
  }
}

Wrong return example：

{"code":xxx,"message":"Illegal device"}

Update user expiration date

Description

Update user expiration date of devices.

Request URL

See the unique request URL.
Method: tts.user.device.expiration.update

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

Response

result list：

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "imei": "868120145233604",
      "update_result": "0",
      "update_msg": "update success"
    },
    {
      "imei": "868120145233605",
      "update_result": "1",
      "update_msg": "update failed, reason:xxxxxx"
    }
  ]
}

Wrong return example：

{"code":xxx,"message":"Illegal device"}

Get the mileage data of devices

Description

Get device(s) trips data of specified time range.

Request URL

See the unique request URL.
Method: tts.device.track.mileage

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

result list：

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "imei": "3505831983422342",
      "startTime": "2017-04-26 00:00:58",
      "endTime": "2017-04-26 00:03:58",
      "startLat": 22.577144898887813,
      "startLng": 113.91674845964586,
      "endLat": 22.677144898887813,
      "endLng": 113.92674845964586,
      "elapsed": 2130,
      "distance": 25000,
      "avgSpeed": 90
    },
    {
      "imei": "3505831983422342",
      "startTime": "2017-04-26 00:00:58",
      "endTime": "2017-04-26 00:03:58",
      "startLat": 22.577144898887813,
      "startLng": 113.91674845964586,
      "endLat": 22.677144898887813,
      "endLng": 113.92674845964586,
      "elapsed": 2130,
      "distance": 25000,
      "avgSpeed": 90
    }
  ],
  "data": [
    {
      "imei": "3505831983422342",
      "totalMileage": 60000
    },
    {
      "imei": "3505831983422342",
      "totalMileage": 60000
    }
  ]
}

Get the track data of device

Description

Get device track data of not more than 7 days, within 3 months.

Request URL

See the unique request URL.
Method: tts.device.track.list

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

result list：

data list：

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "lat": 22.577144898887813,
      "lng": 113.91674845964586,
      "gpsTime": "2017-04-26 00:00:58",
      "direction": 0,
      "gpsSpeed": -1,
      "posType": 3,
      "satellite": 0,
      "ignition": "ON",
      "accStatus": "ON"
    },
    {
      "lat": 22.57708,
      "lng": 113.916631,
      "gpsTime": "2017-04-26 00:01:30",
      "direction": 184,
      "gpsSpeed": 0,
      "posType": 1,
      "satellite": 0,
      "ignition": "ON",
      "accStatus": "ON"
    }
  ],
  "data": {
    "mileage": 0
  }
}

Return error example：

{"code":xxx,"message":"IMEI does not exist{353419031939627}"}
{"code":xxx,"message":"The device has expired{353419031939627}"}

Update vehicle information by IMEI

Description

Update vehicle information by IMEI

Request URL

See the unique request URL.
Method: tts.open.device.update

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

Correct return example：

{
  "code": 0,
  "message": "Vehicle information modification successful",
  "result": null
}

Wrong return example：

{"code":xxx,"message":"imei doesn’t exists"}

Vehicle Icon

Get Device Photo or Video URL

Description

Get device photo or video URL which capture by camera.

REMARK: ONLY GET THE VIDEO OR PHOTO WHICH CREATED BY REMOTE COMMAND.
TO GET ALL TYPE PHOTO OR VIDEO, PLEASE USE 7.38 API

Request URL

See the unique request URL.
Method: tts.device.media.URL

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

result list：

Correct return example：

{
  "code": 0,
  "message": "Operation successful",
  "result": [
    {
      "thumb_URL": "Q9GLAFFqfCrYF6YfQAcON4w4Ezs=/lhWse7ie3wtFrjuQZ22dLAk5CSaR",
      "file_URL": "357730090345670_3949477_2019_04_29_12_32_38_01",
      "mime_type": "video/mp4",
      "create_time": "2019-04-29 10:32:43",
      "media_type": 2,
      "camera": 1,
      "file_size": 9949087
    },
    {
      "thumb_URL": "Q9GLAFFqfCrYF6YfQAcON4w4Ezs=/FhCrZEIy3518sR_ylOlqDg7w3Ju-",
      "file_URL": "351609080120911_3949476_2019_04_29_18_32_12",
      "mime_type": "video/3gpp",
      "create_time": "2019-04-29 10:32:42",
      "media_type": 2,
      "camera": 1,
      "file_size": 2411318
    }
  ]
}

Wrong return example：

{"code":xxx,"message":"imei doesn’t exists"}

Get Device Live Steaming Page URL

Description

Get device live streaming page URL & last position information.

Request URL

See the unique request URL.
Method: tts.device.live.page.url

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

result object：

Correct return example：

{
  "code": 0,
  "message": "Vehicle information modification successful",
  "result": {
    "lat": 22.577144898887813,
    "lng": 113.91674845964586,
    "gpsTime": "2017-04-26 00:00:58",
    "direction": 0,
    "gpsSpeed": -1,
    "posType": 3,
    "satellite": 11,
    "VIN": "V12345",
    "plateNo": "ABC-12345",
    "UrlCamera": "https://www.domain.com/device/video/35408343202342345"
  }
}

Wrong return example：

{"code":xxx,"message":"imei doesn’t exists"}

Wi-Fi, Base Station locating analysis

Description

Allocate by total devices under the account (10 times/day/device. All sub-accounts included)

Request URL

See the unique request URL.
Method: tts.lbs.address.get

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

Result list：

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": {
    "lat": 40.65615416521587,
    "lng": 109.89894039833524,
    "accuracy": 0
  }
}

Wrong return example：

{"code":xxx,"message":"illegal device"}

Create Geo-fence for IMEI

Description

Create Geo-fence for IMEI

Request URL

See the unique request URL.
Method: tts.open.device.fence.create

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

Correct return example：

{
  "code": 0,
  "message": "Successfully create geo-fence.",
  "result": "5"
}

Wrong return example：

{
  "code": 41003,
  "message": "Device is not online, geo-fence creation failed ",
  "result": null
}

Delete Geo-fence for device

Description

Delete Geo-fence for device.

Request URL

See the unique request URL.
Method: tts.open.device.fence.delete

HTTP request method

POST

Request parameters

（1）Common parameters

（2）Private parameters

Response

correct return example：

{
  "code": 0,
  "message": "delete the geo-fence successfully",
  "result": null
}

return error example：

{
  "code": 41003,
  "message": "The device is not online and geo-fence can’t be deleted",
  "result": null
}

Get command list supported by device

Description

Get command list supported by device

Request URL

See the unique request URL.
Method: tts.open.instruction.list

HTTP request method

POST

Request parameters

（1）Common parameters

（2）Private parameters

Response

Result list

correct return example：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": 81,
      "orderName": "SOS setting",
      "orderContent": "SOS,A,{0},{1},{2}#",
      "orderExplain": "SOS is used for receive alerts and SOS alerts. SOS number should have 3-20 numbers.",
      "orderMsg": "",
      "isOffLine": "1"
    }
  ]
}

return error example：

{
  "code":xxx,
  "message":"Illegal device"
}

Send command to device

Description

Send command to device.

Request URL

See the unique request URL.
Method: tts.open.instruction.send

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

inst_param_json description

Example:

{"inst_id": "113","inst_template":"RELAY,1#","params":[],"is_cover":"true"}
{"inst_id": "114","inst_template":"RELAY,0#","params":[],"is_cover":"true"}

Example:

{"inst_id": "96","inst_template":"{0}","params":["STATUS#"],"is_cover":"true"}

Response

Correct return example：

{
  "code": 0,
  "message": "command is successfully sent.",
  "result": null
}

Return error example：

{
  "code": 12005,
  "message": "Fail to send command. Result code：226",
  "result": null
}

Get results of command execution

Description

Get results of sending command.

Request URL

See the unique request URL.
Method: tts.open.instruction.result

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

Result list：

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "codeId": "99",
      "code": "status#",
      "content": "Parameter error",
      "isExecute": "4",
      "sendTime": "2017-06-19 11:46:00",
      "sender": "ttstest",
      "receiveDevice": "868120111111117",
      "isOffLine": "1",
      "idsource": "User-defined command"
    }
  ]
}

Return error example：

{"code":xxx,"message":"Illegal device"}

Send raw command data to device

Description

Send raw command to device.

Request URL

See the unique request URL.
Method: tts.open.instruction.raw.send

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

Raw Command Example:

0B02C3A405060708

Response

Correct return example：

{
  "code": 0,
  "message": "command is successfully sent.",
  "result": null
}

Return error example：

{
  "code": 12005,
  "message": "Fail to send command. Result code：226",
  "result": null
}

Push Received Raw Data

Description

Third-party platform should provide an URL (same as messages push URL) to receive the raw data (please contact us and provide the URL manually), TTS server will push the raw data by sending a HTTP request using this URL.

Message service List

Request content

Message content ( tts.open.instruction.raw.receive )

Alarms pushed are as follows：

Example:

Parameter1:
Key = msgType
Value = tts.open.instruction.raw.receive

Parameter2:
Key = data
Value = {
  "imei": "868120145233604",
  "deviceName": "868120145233604",
  "raw_data": "0A0C0F01182E0101"
}

Send media instruction

Description

Send video or photo command to device.

Request URL

See the unique request URL.
Method: tts.device.meida.cmd.send

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters

Response

Success example：

{
  "code": 0,
  "message": "Operation successful",
  "result": {"code":"255","data":"1.3.3","msg":"通信成功响应","cmdSeqNo":"1"}
}

Exception example：

{
  "code": -1,
  "message": "Operation successful",
  "result": {"code":"228","data":"1.3.3","msg":"设备不在线","cmdSeqNo":"1"}
}

Receive Notification

Description

Third-party platform should provide an URL address to receive the notification (please contact us and provide the URL manually), TTS server will push the notification by sending a HTTP request using this URL.

Message service List

Request content

Message content (tts.push.device.alarm)

Alarms pushed are as follows：

E.g：

Parameter1:
    Key = msgType
    Value = tts.push.device.alarm

Parameter2:
    Key = data
    Value = {
        "imei": "868120145233604",
        "deviceName": "868120145233604",
        "alarmType": "2",
        "alarmName": "Power off alarm",
        "lat": 40.65615416521587,
        "lng": 109.89894039833524,
        "alarmTime": "2017-05-08 12:00:00"
    }

Get device alarm list

Description

Get device alarm list.
Time range of searching criteria should be within 1 month.
Return maximum 1000 rows.

Request URL

See the unique request URL.
Method: tts.device.meida.cmd.send

HTTP request method

POST

Request parameters

• Common parameters
• Private parameters

Response

Result list：

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "deviceName": "ABC-34352",
      "imei": "343503422910345",
      "model": "GT06N",
      "account": "test1234",
      "alertTypeId": "1002",
      "alarmTypeName": "ACC On",
      "alertTime": "2019-03-14 14:02:03",
      "positioningTime": "2019-03-14 14:02:03",
      "lat": 22.577144898887813,
      "lng": 113.91674845964586,
      "speed": "10",
      "geoid": "se8yg081p0qh5vnniqrakr1nr0tdh6a0"
    }
  ]
}

Wrong return example：

{"code":xxx,"message":"Illegal device"}

(Deprecated)Send command (for scooter device)

(Deprecated)Get detail information of scooter

Get history video list

Description

Send Historical video file list upload command to device or query file list.
This API interface is only applicable to the old firmware of the JC200 and JC400 models of the platform.
Other models of devices can use API : 7.21 Get Device Live Steaming Page URL

Request URL

See the unique request URL.
Method: tts.device.meida.cmd.send

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

{"code":"100","data":"1.3.3","msg":"Successful response","cmdSeqNo":"1"}

{" 2018_03_29_16_51_45.mp4,2018_03_29_16_52_46.mp4,"}

type=1
Success example

{
  "code": 0,
  "message": "Operation successful",
  "result": {"code":"255","data":"1.3.3","msg":"Successful response","cmdSeqNo":"1"}
}

Exception example

{
  "code": -1,
  "message": "Operation successful",
  "result": {"code":"228","data":"1.3.3","msg":"Device is offline","cmdSeqNo":"1"}
}

type=2

{
  "code": 0,
  "message": "Operation successful",
  "result": "2018_03_29_16_51_45.mp4,2018_03_29_16_52_46.mp4,"
}

Send history video instruction

Description

Send upload history video file command to device.

Request URL

See the unique request URL.
Method: tts.device.history.cmd.send

HTTP request method

POST

Request parameters

• Common parameters
• Private parameters

Response

{"code":"100","data":"1.3.3","msg":"Successful response","cmdSeqNo":"1"}

Success example：

{
  "code": 0,
  "message": "Operation successful",
  "result": {"code":"255","data":"1.3.3","msg":"Successful response","cmdSeqNo":"1"}
}

Exception example：

{
"code": -1,
"message": "Operation successful",
"result": {"code":"228","data":"1.3.3","msg":"Device is offline","cmdSeqNo":"1"}
}

Get video rtmp url

Description

Get video rtmp url

Request URL

See the unique request URL.
Method: tts.open.video.rtmp.url

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

{ "code": 0,"message": "success","result": “rtmp://36.133.0.208:1935/0/353376110035950?uId=openapi8b7914c3e4c188def67edd6b4a743146&vhost=8&user=172&expire_stamp=1595923486798&ext=&channel=0&token=25b422283ff824461b33d8c5059d”}

Success example：

{
  "code": 0,
  "message": "Operation successful",
  "result": “rtmp://36.133.0.208:1935/0/353376110035950?uId=openapi8b7914c3e4c188def67edd6b4a743146&vhost=8&user=172&expire_stamp=1595923486798&ext=&channel=0&token=25b422283ff824461b33d8c5059d”
}

Exception example：

{
  "code": 228,
  "message": "The device is not online",
  "result": “null”
}

Get Device TTS Photo or Video URL

Description

Get device photo or video URL which capture by camera.

Request URL

See the unique request URL.
Method: tts.device.tts.media.URL

HTTP request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

result list:

Remark: Unix timestamp; Example: 1611105520 = 2021-01-20 09:18:40

Correct return example:

{
  "code": 0,
  "message": "Operation successful",
  "result": 
[
        {
            "thumb_URL": "http://8.210.205.58:8081/normal/get?fileKey=2021_01_20_09_17_49_I_28.jpg",
            "file_URL": "http://8.210.205.58:8081/normal/get?fileKey=357730090564767_29057540_2021_01_20_09_17_49_I_28_128.mp4",
            "create_time": 1611105520,
            "mime_type": "video/mp4",
            "media_type": 2,
            "alarm_time": 1611105469,
            "camera": 0,
            "file_size": "12108649"
        },
        {
            "thumb_URL": "http://8.210.205.58:8081/normal/get?fileKey=2021_01_20_08_06_13_I_56.jpg",
            "file_URL": "http://8.210.205.58:8081/normal/get?fileKey=357730090564767_00000000_2021_01_20_08_06_13_I_56_146.mp4",
            "create_time": 1611101264,
            "mime_type": "video/mp4",
            "media_type": 2,
            "alarm_time": 1611101173,
            "camera": 0,
            "file_size": "48452069"
        }
]
}

Wrong return example:

{"code":xxx,"message":"imei doesn’t exists"}

Edit user information

Description

Edit the user information of the platform, only edit the user's nickname, mobile phone number, email address, contact person, company name and permissions.

Request URL

See the unique request URL.
Method: tts.user.child.update

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters

Response

Correct return example：

{
"code": 0,
"message": "Account update success!",
"result": null,
"data": null
}

Get parking/idling data of devices

Description

Get device(s) parking/idling data of specified time range.

Request URL

See the unique request URL.
Method: tts.open.platform.report.parking

HTTP Request method

POST

Request parameters

Response

data list

rows object

Success example

{ 
"code": 0, 
"message": "success", 
"result": null , 
"data": {
"totalTime":"185641",
"dataTotalRows":"2",
"rows":[
   {
"imei":"869247060001739",
"startTime":"2022-12-10T01:05:33.000Z",
"endTime":"2022-12-10T04:17:48.000Z",
"durSecond":"11535",
"lng":113.943093,
"lat":22.576748,
"addr":"Shigu Road, 松坪村, Xili Sub-district, Nanshan distri...",
"deviceName":"JC450Pro-01739",
"mcType":"JC450Pro",
"acc":"on",
"stopSecond":"11535"
},
   {
"imei":"869247060001739",
"startTime":"2022-12-09T22:13:16.000Z",
"endTime":"2022-12-10T01:04:25.000Z",
"durSecond":"10269",
"lng":113.943002,
"lat":22.57649,
"addr":"Shigu Road, 松坪村, Xili Sub-district, Nanshan distri...",
"deviceName":"JC450Pro-01739",
"mcType":"JC450Pro",
"acc":"on",
"stopSecond":"10269"
      }
   ]
  }
}

Wrong return example：

{ 
"code": 1100, 
"message": "Business exception ", 
"result": null ,
"data": null ,
}

Create platform Geo-fence

Description

Create a platform geofence, the newly created platform geofence belongs to the default group.

Request URL

See the unique request URL.
Method: tts.open.platform.fence.create

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": null,
  "data": "c33b80d46d2b41d588a5afbd6f8b6285"
}

Wrong return example:

{
  "code": 1114,
  "message": "That name already exists",
  "result": null,
  "data": null
}

Edit platform Geo-fence

Description

Edit platform geofence informatio.

Request URL

See the unique request URL.
Method: tts.open.platform.fence.create

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": null,
  "data": "c33b80d46d2b41d588a5afbd6f8b6285"
}

Wrong return example:

{
  "code": -1,
  "message": "The system is busy",
  "result": null,
  "data": null
}

Delete platform Geo-fence

Description

Delete platform geofence.

Request URL

See the unique request URL.
Method: tts.open.platform.fence.delete

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": null,
  "data": null
}

Wrong return example:

{
  "code": -1,
  "message": " The system is busy ",
  "result": null,
  "data": null
}

Geo-fence related device

Description

Geofence related device.

Request URL

See the unique request URL.
Method: tts.open.platform.fence.bind

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": null,
  "data": "3"
}

Wrong return example:

{
  "code": 1100,
  "message": "Business exception",
  "result": null,
  "data": null
}

List platform geofences of an account

Description

Query platform geofences of a specified account.

Request URL

See the unique request URL.
Method: tts.open.platform.fence.list

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

result:

Rows list:

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": {
    "total": 294,
    "rows": [
      {
        "fence_id": "dfab43ea3e7a40e987056c857cccae7b",
        "fence_name": "test fence",
        "fence_type": "circle",
        "fence_color": "#3b7aff",
        "coordinates": "22.544382,114.004037",
        "radius": "4153",
        "description": "",
        "imeis": "231011234567990,869247060001655,868598060001827,869247060001259",
        "alert_type": "in",
        "stay_time_out": null,
        "stay_time_in": null,
        "account": "hao001"
      }
    ]
  }
}

Wrong return example:

{
  "code": -1,
  "message": "The system is busy",
  "result": null,
  "data": null
}

Move devices

Description

Move devices from one sub-account to another sub-account.

Request URL

See the unique request URL.
Method: tts.open.device.move

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example:

{
  "code": 1112,
  "message": "device already exists",
  "result": [
    "202205454545454"
  ],
  "data": null
}

Or:

{
  "code": 0,
  "message": "Transfer/Sell Equipment Successfully",
  "result": null,
  "data": null
}

Wrong return example:

{
  "code": xxx, "message": "no permissions"
}

Get RFID reporting information

Description

Query the RFID information reported within a certain period of time.

Request URL

See the unique request URL.
Method: tts.open.device.rfid.list

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

data object：

result list：

Correct return example:

{
  "code": 0,
  "message": "success",
  "data": {
    "currentPage": 1,
    "pageSize": 10,
    "startRow": 1,
    "endRow": 10,
    "totalRecord": 34,
    "totalPage": 4,
    "result": [
      {
        "imei": "890768902346789",
        "cardId": "278907",
        "operationTime": "2024-04-22 09:12:23",
        "photo": ""
      }
    ]
  }
}

Wrong return example:

{"code":xxx,"message":"no permissions"}

Query single fence information

Description

Query single fence information based on fence id

Request URL

See the unique request URL.
Method: tts.open.platform.fence.detail

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

result:

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": {
    "fence_id": "dfab43ea3e7a40e987056c857cccae7b",
    "fence_name": "test fence",
    "fence_type": "circle",
    "fence_color": "#3b7aff",
    "coordinates": "22.544382,114.004037",
    "radius": "4153",
    "description": "",
    "imeis": "231011234567990,869247060001655,868598060001827,869247060001259",
    "alert_type": "in",
    "stay_time_out": null,
    "stay_time_in": null,
    "account": "hao001"
  }
}

Wrong return example:

{
  "code": -1,
  "message": "The system is busy",
  "result": null,
  "data": null
}

Bind app user

Description

Bind the device to the app user.

Request URL

See the unique request URL.
Method: tts.open.device.bind

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example:

{
  "code": 0,
  "message": "success"
}

Wrong return example:

{
  "code": 1100,
  "message": "The system is busy",
  "result": null,
  "data": null
}

Unbind app user

Description

Unbind the device from the app user.

Request URL

See the unique request URL.
Method: tts.open.device.unbind

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example:

{
  "code": 0,
  "message": "success"
}

Wrong return example:

{
  "code": 1100,
  "message": "The system is busy",
  "result": null,
  "data": null
}

Get the trips report data of devices

Description

Query the trips report data of devices.

Request URL

See the unique request URL.
Method: tts.open.platform.report.trips

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

data list：

datDatas list:

datDatas.data:

dayList list：

dayList.tripsData：

dayList.tripsData.dayData:

Correct return example：

暂缺

Wrong return example:

{
  "code": 1100,
  "message": "Business exception",
  "result": null,
  "data": null
}

Get entry and exit fence data of devices

Description

Query the report data of the device's entry and exit fence.

Request URL

See the unique request URL.
Method: tts.open.platform.fence.duration

HTTP Request method

POST

Request parameters

• (1) Common parameters
• (2) Private parameters as follow:

Response

data list：

Rows list

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": null,
  "data": {
    "totalTime": "0",
    "dataTotalRows": "2",
    "rows": [
      {
        "imei": "869247060001739",
        "deviceName": "JC450Pro-01739",
        "fenceName": "geofence1",
        "enterTime": "2022-12-10T01:05:33.000Z",
        "exitTime": "2022-12-10T04:17:48.000Z",
        "duration": "11535"
      },
      {
        "imei": "869247060001739",
        "deviceName": "JC450Pro-01739",
        "fenceName": "geofence1",
        "enterTime": "2022-12-10T01:05:33.000Z"
      }
    ]
  }
}

Wrong return example：

{
  "code": 1100,
  "message": "Business exception",
  "result": null,
  "data": null
}

Get the OBD data of devices

Description

Query CAN bus diagnosis data reported by OBD device.

Request URL

See the unique request URL.
Method: tts.device.obd.list

HTTP Request method

POST

Request parameters

• (1) Common parameters
• (2) Private parameters as follow:

Response

data list：

rows list：

Correct return example：

{
    "code": 0,
    "message": "success",
    "data": {
        "currentPage": 1,
        "pageSize": 2,
        "startRow": 0,
        "endRow": 0,
        "totalRecord": 2684,
        "totalPage": 0,
        "result": [
            {
                "imei": "158511020000028",
                "dataReportTime": "2024-05-09 10:25:00",
                "odometerReading": "2049.6",
                "deviceAccumulatedMileage": "142.9",
                "remainingFuel": null,
                "remainingFuelPercentage": "58",
                "coolantTemperature": "77",
                "vehicleBatterVoltage": "118",
                "currentRPM": "5016",
                "currentSpeed": "88.5",
                "vin": "LC0CG4CF1H0029191"
            },
            {
                "imei": "158511020000028",
                "dataReportTime": "2024-05-09 1:27:23",
                "odometerReading": "2048.6",
                "deviceAccumulatedMileage": "143.9",
                "remainingFuel": null,
                "remainingFuelPercentage": "56",
                "coolantTemperature": "78",
                "vehicleBatterVoltage": "118",
                "currentRPM": "5016",
                "currentSpeed": "95.5",
                "vin": "LC0CG4CF1H0029191"
            }
        ]
    }
}

Wrong return example：

{
    "code": 1100,
    "message": "Business exception ",
    "result": null,
    "data": null
}

Get the OBD fault data of devices

Description

Query CAN bus fault code information reported by OBD device.

Request URL

See the unique request URL.
Method: tts.device.obd.fault

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）Private parameters as follow:

Response

data list：

rows list：

Correct return example：

{
    "code": 0,
    "message": "success",
    "result": null,
    "data": {
        "currentPage": 1,
        "pageSize": 4,
        "startRow": 0,
        "endRow": 0,
        "totalRecord": 6,
        "totalPage": 0,
        "result": [
            {
                "imei": "202509999999994",
                "deviceName": "VL502_E-99994",
                "faultCode": "P1502",
                "faultDetail": "High speed state of the vehicle - the front axle is faster than the rear axle",
                "eventTime": "2024-07-03 08:16:49"
            },
            {
                "imei": "202509999999994",
                "deviceName": "VL502_E-99994",
                "faultCode": "B0074",
                "faultDetail": "2nd row center seat belt pretensioner - start control (sub-error)",
                "eventTime": "2024-07-03 08:26:49"
            },
            {
                "imei": "202509999999994",
                "deviceName": "VL502_E-99994",
                "faultCode": "P2407",
                "faultDetail": "Fuel evaporative emission system leak detection pump sensing circuit is intermittent/unstable",
                "eventTime": "2024-07-03 08:36:49"
            },
            {
                "imei": "202509999999994",
                "deviceName": "VL502_E-99994",
                "faultCode": "U0464",
                "faultDetail": "Invalid data received from the navigation control module",
                "eventTime": "2024-07-03 08:46:49"
            }
        ]
    }
}

Wrong return example：

{
    "code": 1100, 
    "message": "Business exception ", 
    "result": null ,
    "data": null ,
}

Get the location of TAG device

Description

Query the latest location of TAG.

Request URL

See the unique request URL.
Method: tts.device.location.getTagMsg

HTTP Request method

POST

Request parameters

• (1) Common parameters
• (2) Private parameters as follow:

Response

result list：

Correct return example：

{
    "code": 0,
    "message": "success",
    "result": [
        {
            "lng": 113.943054,
            "lat": 22.576609,
            "gpsTime": 1734593340,
            "directions": "0",
            "gpsSpeed": -1.0,
            "positionType": "5",
            "gpsNum": 3
        }
    ]
}

Wrong return example：

{
    "code": 1100,
    "message": "Business exception ",
    "result": null,
    "data": null
}

Create device group

Description

Add device groups.
Users can divide devices into different groups for easier management.

Request URL

See the unique request URL.
Method: tts.device.group.create

HTTP Request method

POST

Request parameters

• (1) Common parameters
• (2) Private parameters as follow:

Response

result

Correct return example：

{
    "code": 0,
    "message": "success",
    "result": {
        "group_id": "534d23f1b28c44319f4f8ba0cda5b7e6",
        "group_name": "device group 1"
    }
}

Edit device group

Description

Edit device groups.

Request URL

See the unique request URL.
Method: tts.device.group.update

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example：

{
    "code": 0,
    "message": "success"
}

Delete device group

Description

Delete device groups.

Request URL

See the unique request URL.
Method: tts.device.group.delete

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

Correct return example：

{
    "code": 0,
    "message": "success"
}

Get device group list of an account

Description

Query the device groups of an account.

Request URL

See the unique request URL.
Method: tts.device.group.list

HTTP Request method

POST

Request parameters

• （1）Common parameters
• （2）private parameters as follow:

Response

rows list：

Correct return example：

{
    "code": 0,
    "message": "success",
    "result": [
        {
            "group_id": "b2ac10536171474eb0c151c7bb606f3d",
            "group_name": "Default group"
        },
        {
            "group_id": "298b949bacbb4badae597ba1fdb629be",
            "group_name": "22221"
        },
        {
            "group_id": "05cbdd380ca14c2e89b2ab59904f51b7",
            "group_name": "CVCVXCV"
        }
    ]
}

Appendix

Device alarm type(alarm type Id)

The alarm type ID of the alarm type actively reported by the device is a number.
The alarm type ID of the alarm generated after platform logic judgment is English text.