# Segway API-Max Plus
Welcome to the Segway API of Gateway. This API reference provides information on available endpoints and how to interact with them.
Using the Segway API of Gateway, you can integrate vehicle data and control into your applications.
The API uses JSON formatted requests and responses.
Note1: please request the relevant domian according to the first letter of your platformcode
| platformCode | region | domain |
|---|---|---|
| A***** | apac | https://apac-api.segwaydiscovery.com |
| E***** | europe | https://eu-api.segwaydiscovery.com |
| U***** | americas | https://us-api.segwaydiscovery.com |
| C***** | china | https://cn-api.segwaydiscovery.com |
# Auth
# request token common for all models
The access_token is the globally unique credential for calling APIs, and needs to be updatad periodically. The validity period of access_token is expressed in the returned expires_in, and its available value is within 86400 seconds. Your server needs to updata access_token in advance based on this validity period. During the updata, it may continue to output old access_token values. In this case, the SEGWAY backend will ensure that both new and old access_token values are available within 300 seconds(expires_in≤300), so that third-party services are smoothly transitioned.
POST
/oauth/token
curl -X POST \
https://api_domain:port/oauth/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=A20081' \
--data-urlencode 'client_secret=e2651be5-12d3-48f3-ba6c-bc2b04a447b6' \
--data-urlencode 'grant_type=client_credentials'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/x-www-form-urlencoded" |
Parameter
| field | type | description |
|---|---|---|
| client_id | String | get from business system |
| client_secret | String | get from business system |
| grant_type | String | allowed: "client_credentials" |
Success
| field | type | description |
|---|---|---|
| access_token | String | token |
| token_type | String | allowed values: "bearer" |
| expires_in | Int | expiration duration seconds. |
| scope | String | scope. |
HTTP/1.1 200 OK
{
"access_token": "83efe135-8203-404c-b489-b5fbf8050d3d",
"token_type": "bearer",
"expires_in": 43199,
"scope": "read write trust"
}
False
1.0 HTTP/1.1 401 Unauthorized
{
"error": "invalid_client",
"error_description": "Bad client credentials"
}
# Query
# get current status common for all models
This API is used to obtain the realtime status information.
GET
/api/v2/vehicle/query/current/status
curl -X GET \
https://api_domain:port/api/v2/vehicle/query/current/status?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'
Header
| field | type | description |
|---|---|---|
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
attached:'data'
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| online | Boolean | true→ connected to SEGWAY Cloud. false→ disconnected |
| locked | Boolean | true→ lock. false→ unlock |
| lockVoltage | Number | lock voltage, unit/mV |
| networkSignal | Number | network signal. range: 2-32. 2 shows the signal is weakest, 32 shows the signal is strongest. |
| charging | Boolean | true→charging. false→ no charging |
| powerPercent | Number | battery percentage, 80->80%. |
| speedMode | Number | speed mode (1: low speed; 2: medium speed; 3: high speed |
| speed | Number | current speed |
| odometer | Number | total odometer (unit is 1m, so 1230 means 1.23km) |
| remainingRange | Number | remaining range (unit is 10m, so 1230 means 12.3km) |
| totalRidingSecs | Number | total riding seconds. |
| statusUtcTime | Number | timestamp |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": {
"iotCode": "{iotCode}",
"online": true,
"locked": true,
"lockVoltage": 342,
"networkSignal": 22,
"charging": true,
"powerPercent": 10,
"speedMode": 1,
"speed": 20,
"odometer": 9000,
"remainderRange": 3000,
"totalRidingSecs": 110,
"statusUtcTime": 1591067719
},
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# get current location common for all models
This API is used to obtain the location information.
GET
/api/v2/vehicle/query/current/location
curl -X GET \
https://api_domain:port/api/v2/vehicle/query/current/location?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'
Header
| field | type | description |
|---|---|---|
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| realTimeLocation(optional) | Boolean | true-> will get real time location information |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
attached:'data'
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| latitude | Double | latitude (WGS84). |
| longitude | Double | longitude (WGS84). |
| satelliteNumber | Number | gps satellite Number. |
| hdop | Number | gps hdop, more lower is the value, the higher is the accuracy. |
| altitude | Number | altitude (height from sea level), Unit Meter |
| gpsUtcTime | Number | timestamp |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "success",
"data": {
"iotCode": "{iotCode}",
"latitude": 22.634228,
"longitude": 114.125962,
"satelliteNumber": 6,
"hdop": 1.38,
"altitude": 10.1,
"gpsUtcTime": "1591067719"
},
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15400 | latest location not found via device |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# get battery Info common for scooters(ES,Max,MaxPro,MaxPlus)
This API is used to get the scooter's battery information.
GET
/api/v2/vehicle/query/current/battery-info
curl -X GET \
https://api_domain:port/api/v2/vehicle/query/current/battery-info?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'
Header
| field | type | description |
|---|---|---|
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
attached:'data'
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| charging | Boolean | true→charging. false→ no charging |
| controllerVoltage | String | controller voltage,412->4.12V |
| batteryData | list | Object list: 'battery data' |
attached：'battery data'
| field | type | description |
|---|---|---|
| batteryPercent | Number | batterypercent, unit/80->80% |
| cycleTimes | Number | cycleTimes |
| temperatrue1 | Number | temperatrue1, unit/℃ |
| temperatrue2 | Number | Temperatrue2, unit/℃ |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "success",
"data": {
"iotCode": "{iotCode}",
"charging": true,
"controllerVoltage": 26,
"batteryData": [
{
"batteryPercent": 52,
"cycleTimes": 23,
"temperatrue1": 25,
"temperatrue2": 25
}]
},
"t": 1593333694412,
"resId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"resId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# get bluetooth key common for all models
This API is used to get IoT's bluetooth key
GET
/api/v2/vehicle/query/current/bluetooth-key
curl -X GET \
https://api_domain:port/api/v2/vehicle/query/current/bluetooth-key?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'
Header
| field | type | description |
|---|---|---|
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
attached:'data'
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| key | String | 8 digit letters and Numbers. eg:'abcd1234' |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "success",
"data": {
"iotCode": "{iotCode}",
"key": "abcd1234"
},
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15400 | latest location not found via device |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# get component status
This API is used to obtain the the current status of components.
GET
/api/v2/vehicle/query/component-status
curl -X GET \
https://api_domain:port/api/v2/vehicle/query/component-status?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'
Header
| field | type | description |
|---|---|---|
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
attached:'data'
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| helmetLockStatus | Number | 0:Unlocked 1:locked |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "success",
"data": {
"iotCode": "{iotCode}",
"helmetLockStatus": "0"
},
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# get helmet lock info
This API is used to obtain the the Bluetooth info(MAC address and key) of the helmet lock.
GET
/api/v2/vehicle/query/helmet-lock-info
curl -X GET \
https://api_domain:port/api/v2/vehicle/query/chelmet-lock-info?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'
Header
| field | type | description |
|---|---|---|
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| searchKey | String | IoT IMEI or helmet lock MAC address |
| searchBy | Number | 0: IoT IMEI 1: helmet lock MAC address |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
attached:'data'
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| bleMAC | String | helmet lock Bluetooth MAC address, with colon ":". if there is no helmet lock bind to this vehicle, this field will be the empty string. |
| bleKey | String | helmet lock Bluetooth Key if there is no helmet lock bind to this vehicle, this field will be the empty string. |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "success",
"data": {
"iotCode": "{iotCode}",
"bleMAC": "12:34:56:78:90:AB",
"bleKey": "12345678",
},
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
HTTP/1.1 200 OK
{
"code": 15102,
"msg": "device not found",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# Control
# unlock common for all models
This API is used to unlock the vehicle
POST
/api/v2/vehicle/control/unlock
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/unlock \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116"
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593331167570,
"opId": "d5aa020d-77ae-439c-892c-a781c71eb836"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
| 10 | 15611 | device unlock command failed |
| 11 | 15612 | device unlock failed: network error |
| 12 | 15990 | API call is restricted, please contact Segway related personnel |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# lock common for all models
This API is used to lock the vehicle
POST
/api/v2/vehicle/control/lock
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/lock \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116"
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
| 10 | 15600 | lock failed: vehicle is riding |
| 11 | 15601 | device lock command failed |
| 12 | 15602 | device lock failed: network error |
| 13 | 15996 | device lock failed: denied by geofence strategy |
| 14 | 15997 | device lock failed: unable to lock while riding |
| 15 | 15990 | API call is restricted, please contact Segway related personnel |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# headlight deprecated, recommend to use 'light' portal
This API is used to turn the vehicle's headlight on or off.
POST
/api/v2/vehicle/control/headlight
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/headlight \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data-raw '{
"iotCode" : "861477038719116",
"controlType" : 0
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| controlType | Number | 0→ turn off. 1→ turn on |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# light common for scooters(ES,Max,MaxPro,MaxPlus). please updata iot F/W to the special version
This API is used to turn the vehicle's light flicker on/off.
POST
/api/v2/vehicle/control/light
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/light \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode": "861477038719116",
"headLight": 0,
"tailLight": 0
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| headLight(optional) | Number | 0→ off, 1→ on, 2→flicker |
| tailLight(optional） | Number | 0→ off, 1→ on, 2→flicker |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# light flicker deprecated, recommend to use 'light' portal
This API is used to turn the vehicle's light flicker on/off.
POST
/api/v2/vehicle/control/light-flicker
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/light-flicker \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode": "861477038719116",
"headLightFlicker": 0,
"tailLightFlicker": 0
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| headLightFlicker | Number | 0→ turn off. 1→ turn on |
| tailLightFlicker | Number | 0→ turn off. 1→ turn on |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# throttle response common for (ES,Max,MaxPro,MaxPlus,E-moped)
This API is used to turn the vehicle's throttle response on/off.
POST
/api/v2/vehicle/control/throttle-response
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/throttle-response \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116",
"controlType" : 1
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| controlType | Number | 0→ turn off. 1→ turn on |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# battery component common for (MaxPro,MaxPlus,E-moped)
This API is used to open the battery compartment.
POST
/api/v2/vehicle/control/battery-cover
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/battery-cover \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116"
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | iot imei |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# mech lock only for some mechanical locks
This API is used to open the mech lock.
NOTE
This function is only supported by some version of IoT firmware: IoT version should >= 130, or you'll get an error with code 15707.
POST
/api/v2/vehicle/control/mech-lock
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/mech-lock \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116"
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
| 10 | 15707 | NOT supported by this vehicle or its firmware |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# sound common for all models
This API is used to sound the vehicle.
POST
/api/v2/vehicle/control/sound
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/sound \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116",
"controlType" : 3
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| controlType | Number | 1→driving out of Geo-fence. 2→toot. 3→low battery percentage |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# power on/off common for scooters(ES,Max,MaxPro,MaxPlus)
This API is used to power the vehicle on/off
POST
/api/v2/vehicle/control/power
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/power \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116",
"controlType" : 1
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| controlType | Number | 0→ power off. 1→ power on |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# ambient
This API is used to set the atmosphere lamp effect, it will works immediatelly until the next time the vehicle’s status is switched or the next time you set.
NOTE
This function is only supported by some scooters which deployed atmosphere lamp around the chassis.
POST
/api/v2/vehicle/control/ambient
curl -X GET \
https://api_domain:port/api/v2/vehicle/control/ambient \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : 862785041281554,
"controlType": 1
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| bright | Number | 0:Default brightness |
| mode | Number | 0:Auto 1:Off 2:Always on 4:Breathing |
| color | Number | 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15303 | command send failed |
| 8 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15300,
"msg": "inactive device",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# transport mode common for scooters(ES,Max,MaxPro,MaxPlus)
This API is used to set the vehicle into the transportation mode in which vehicle will be powered off. Vehicle in transportation mode will be in offline state. We suggest using this command when your scooters won't be deployed and will be kept in the warehouse for months
POST
/api/v2/vehicle/control/whole-shutdown
curl -X GET \
https://api_domain:port/api/v2/vehicle/control/whole-shutdown \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : 862785041281554
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15303 | command send failed |
| 8 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15300,
"msg": "inactive device",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# helmet
This API is used to control the helmet component.
POST
/api/v2/vehicle/control/helmet
curl -X GET \
https://api_domain:port/api/v2/vehicle/control/helmet \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : 862785041281554
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| controlType (optional) | Integer | 0→ unlock (default) 1→ lock |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
| 10 | 15611 | device unlock command failed |
HTTP/1.1 200 OK
{
"code": 15300,
"msg": "inactive device",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# Setting
# switch setting
This API is used to turn on or off the switch.
POST
/api/v2/vehicle/setting/switch
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/switch \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| alertSensitivity(optional) | Number | strength range: 1-3 |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# switch enable
This API is used to enable or disable the switch of vehicles.
NOTE
This function is only supported by some version of IoT firmware, please pay attention to the Note in description for each field, or you'll get an error with code 15707.
POST
/api/v2/vehicle/setting/able-switch
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/able-switch \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| assistedMode(optional) | Number | Power-assisted manual push mode switch 0→ no setting 1→off. 2→on Note: IoT version should >= R20A01V03/R21A01V01 |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
| 10 | 15707 | NOT supported by this vehicle or its firmware |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# scooter settings common for scooters(ES,Max,MaxPro,MaxPlus)
This API is used to set the scooter’s parameters.
POST
/api/v2/vehicle/setting/scooter
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/scooter \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116",
"bssDisplay": 0,
"cruiseControl" : 1,
"buttonSwitchSpeedMode" : 0,
"lowSpeedLimit":6,
"mediumSpeedLimit":18,
"highSpeedLimit":25
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| bssDisplay(optional) | String | displayed as bbs(British Standard speed). 0→ turn off. 1→ turn on |
| cruiseControl(optional) | Number | 0→ turn off. 1→ turn on |
| buttonSwitchSpeedMode(optional) | Number | use button to switch speed mode. 0→ turn off. 1→ turn on |
| lowSpeedLimit(optional) | Number | Size range: 6-25. unit：km/h |
| mediumSpeedLimit(optional) | Number | size range: 6-25. unit：km/h |
| highSpeedLimit(optional) | Number | size range: 6-25. unit：km/h |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# atmosphere lamp setting
This API is used to set relevant parameters of the vehicles.
NOTE
This function is only supported by some scooters which deployed atmosphere lamp around the chassis.
POST
/api/v2/vehicle/setting/ambient
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/ambient \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode":"8612345678901",
"bright": 0,
"lockedMode": {
"mode": 1
},
"readyMode": {
"mode": 2,
"color": 3
}
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| bright | Number | Common atmosphere lamp brightness of each mode. 0:Default Brightness |
| lockedMode | Object | An object that indicates the atmosphere lamp effect |
| readyMode | Object | An object that indicates the atmosphere lamp effect |
attached:'lockedMode,readyMode'
| field | type | description |
|---|---|---|
| mode | Number | 1:Off 2:Always on 4:Breathing |
| color | Number | 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# sound setting
This API is used to set relevant parameters of the vehicle.
NOTE
This function is only supported by some version of IoT firmware, please pay attention to the Note in description for each field, or you'll get an error with code 15707.
POST
/api/v2/vehicle/setting/sound
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/sound \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode": "861477038719116",
"workMode":2,
"volume":3
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| workMode | Number | used to set the device sound 0 →no setting, 1→off, 2→on |
| volume | Number | Volume (1-3）: 1 is the smallest and 3 is largest. |
| sctqMask(optional) | Object | An object to indicate whether it's on or off for each sound of the vehicle. Each element in the object indicates a certain sound. Note: IoT version should >= R20A01V03/R21A01V01 |
attached:'sctqMask'
| field | type | description |
|---|---|---|
| powerOn (optional) | Number | 0:disable 1:enable 2:keep original |
| locked (optional) | Number | 0:disable 1:enable 2:keep original |
| unlocked (optional) | Number | 0:disable 1:enable 2:keep original |
| outofGeofence (optional) | Number | 0:disable 1:enable 2:keep original |
| alarm (optional) | Number | 0:disable 1:enable 2:keep original |
| locating (optional) | Number | 0:disable 1:enable 2:keep original |
| beep (optional) | Number | 0:disable 1:enable 2:keep original |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
| 10 | 15707 | NOT supported by this vehicle or its firmware |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# speed mode common for scooters(ES,Max,MaxPro,MaxPlus)
This API is used to set speed mode.
POST
/api/v2/vehicle/setting/speed-mode
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/speed-mode \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode": "861477038719116",
"speedMode":1
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| speedMode | Number | 1→ low speed. 2→ medium speed. 3→ high speed |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# battery display
There is a way to show the battery percentage on the display when unlock by pressing the throttle switch. If you need this, turn on the battery percentage display switch.
POST
/api/v2/vehicle/setting/battery-display-enable
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/battery-display-enable \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode": "861477038719116",
"controlType":2
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| controlType | Number | used to turn off/on the battery percentage display when the vehicle is unlocked. 1→off 2→on |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# bluetooth key common for all models
This API is used to set IoT's bluetooth key
POST
/api/v2/vehicle/setting/bluetooth-key
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/bluetooth-key \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode": "861477038719116",
"key": "4BKNwi77"
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| key | String | 8 digit letters and Numbers. eg 'abcd1234' |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# upload interval
This API is used to set the upload interval of status and location
NOTE
This function is only supported by some version of IoT firmware: IoT version should >= R20A01V03/R21A01V01, or you'll get an error with code 15707.
POST
/api/v2/vehicle/setting/interval
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/interval \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| locationInterval | Object | request data |
| statusInterval | Object | request data |
attached:'locationInterval'
| field | type | description |
|---|---|---|
| unlockStatus | Number | interval range: 10-65535 |
| lockStatus | Number | interval range: 10-65535 |
attached:'statusInterval'
| field | type | description |
|---|---|---|
| ridingStatus | Number | interval range: 10-65535 |
| nonRiding | Number | interval range: 10-65535 |
| lockStatus | Number | interval range: 10-65535 |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
| 10 | 15707 | NOT supported by this vehicle or its firmware |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# NFC Tag
This API is used to set the NFC work-mode and its tag info.
POST
/api/v2/vehicle/setting/nfc-tag
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/nfc-tag \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116",
"workMode": 0,
"tagData" : "0123456789a-zA-Z-_0123456789a-zA-Z-_"
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| workMode | Number | 0→ Enable NFC card emulation.1→ Disabled. |
| tagData (Optional) | String | tag info string, length: <= 36Bytes, format: ‘0’–’9’, ‘a’–‘z’, ‘A’–’Z’, ‘-’, ‘_’. |
Success
| field | type | description |
|---|---|---|
| code | Number | status code |
| msg | String | messages |
| data | Object | response data |
| t | Number | timestamp |
| opId | String | operation Id |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "Success",
"data": null,
"t": 1593333983900,
"opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}
False
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15004 | parameter error |
| 3 | 15001 | server error |
| 4 | 15102 | device not found |
| 5 | 15300 | inactive device |
| 6 | 15301 | offline device |
| 7 | 15302 | device response timeout |
| 8 | 15303 | command send failed |
| 9 | 15500 | device upgrading: command can not be executed |
| 10 | 15998 | The data length of the NFC Tag information exceeds the maximum limit |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# Push
If your server has received any one of the following types of pushes and successfully processes it, please return an HTTP response code of 200. Otherwise, our server will retry in 5 seconds, this retry will only be done once.
signature generation algorithm
Note: All received parameters except signature are involved in the verification process.
Step 1: If the received data is a String, use “&” and “=” to split the String into several key-value pairs. If the received data is an array, dict, or similar data type, continue as usual and order the received key-value pairs sequentially by ASCII.
Step 2: Convert the sorted dict back into a String in “key1=value1&key2=value2” form.
Step 3: Append “&client_secret=” to the String created during step 2.
Step 4: Use MD5 to calculate the hash value (finally converted into 32-bit hexadecimal characters) of the String created during step 3. The newly calculated value is your digital signature.
Next, compare this value with your signature. If they are the same, the signature verification was successful.
• When performing signature verification, do not enumerate the signature fields according to the port documentation list.
All received parameters except signature are involved in the verification process. When performing signature verification, do not enumerate the signature fields according to the port documentation list. This will cause use many problems if new fields are created.
# vehicle alert common for all models
This API should be exposed by your application system to receive the vehicle’s alerts.
POST
/v2/vehicle/alert
curl -X POST \
https://business:port/v2/vehicle/alert\
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&statusUtcTime={tinmstamp}&code={code}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/x-www-form-urlencoded" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| platformCode | String | client_id |
| statusUtcTime | Number | timestamp |
| alertStatus | Number | 0→ appearing. 1->disappeared |
| code | Number | available appearing alert code: 1->illegal moving. 2->vehicle fell down when locked. 3->illegal dismantling. 4->vehicle fell down when unlocked. 13->brake line looseness detection 14->tandem riding detection available disappeared alert code: 1->illegal moving. 2->vehicle fell down. 3->illegal dismantling. 13->brake line looseness detection 14->tandem riding detection |
| signature | String | more info |
response
| field | type | description |
|---|---|---|
| message(optional) | String | - |
| code | Number | allowed: 0 |
HTTP/1.1 200 OK
{
“message”:success，
“code”: 0
}
# vehicle fault common for all models
This API should be exposed by your application system to receive the vehicle’s fault codes
POST
/v2/vehicle/fault
curl -X POST \
https://business:port/v2/vehicle/fault \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&statusUtcTime={tinmstamp}&faultStatus={disappered}&code={code}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/x-www-form-urlencoded" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| platformCode | String | client_id |
| statusUtcTime | Number | timestamp |
| faultStatus | Number | 0→ appearing. 1->disappeared |
| code | Number | fault code |
| signature | String | more info |
response
| field | type | description |
|---|---|---|
| message(optional) | String | - |
| code | Number | allowed: 0 |
HTTP/1.1 200 OK
{
“message”:success，
“code”: 0
}
# vehicle location common for all models
This API should be exposed by your application system to receive the vehicle's location. When the scooter is unlocked, its location will be pushed once every 10 seconds. When the scooter is locked, its location will be pushed every 900 seconds.
POST
/v2/vehicle/location
curl -X POST \
https://business:port/v2/vehicle/location \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&locationStatus={valid}&latitude={latitude}&longitude={longitude}&satelliteNumber={satelliteNumber}&hdop={hdop}&altitude={altitude}&gpsUtcTime={gpsUtcTime}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/x-www-form-urlencoded" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| platformCode | String | client_id |
| locationStatus | String | allowed: 'invalid' and 'valid' |
| latitude | Double | latitude (WGS84). |
| longitude | Double | longitude (WGS84). |
| satelliteNumber | Number | longitude (WGS84). |
| hdop | Number | gps hdop, more lower is the value, the higher is the accuracy. |
| altitude | Number | altitude (height from sea level), Unit Meter |
| gpsUtcTime | Number | timestamp |
| signature | String | more info |
response
| field | type | description |
|---|---|---|
| message(optional) | String | - |
| code | Number | allowed: 0 |
HTTP/1.1 200 OK
{
“message”:success，
“code”: 0
}
# vehicle status common for all models
This API should be exposed by your application system to receive the changes of the scooter's status. When the scooter is riding, its status will be pushed once every 10 seconds.
POST
/v2/vehicle/status
curl -X POST \
https://business:port/v2/vehicle/status \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&signature={signature}&online={online}&locked={locked} \
&lockVoltage={lockVoltage}&networkSignal={networkSignal}&charging={charging}&powerPercent={powerPercent}&speedMode={speedMode} \
&speed={speed}&odometer={odometer}&remainderRange={remainderRange}&totalRidingSecs={totalRidingSecs} \
&statusUtcTime={statusUtcTime}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/x-www-form-urlencoded" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| platformCode | String | client_id |
| online | Boolean | true→ connected to SEGWAY Cloud. false→ disconnected |
| locked | Boolean | true→ lock. false->unlock |
| lockVoltage | Number | lock voltage, 412->4.12V |
| networkSignal | Number | network signal. range: 2-32. 2 shows the signal is weakest, 32 shows the signal is strongest. |
| charging | Boolean | true→charging. false→ no charging |
| powerPercent | Number | battery percentage, 80->80%. |
| speedMode | Number | speed mode (0: unification status; 1: low speed; 2: medium speed; 3: high speed;) |
| speed | Number | scooter current speed. |
| odometer | Number | total odometer (unit is 1m, so 1230 means 1.23km |
| remainingRange | Number | remaining range (unit is 10m, so 1230 means 12.3km |
| totalRidingSecs | Number | total riding seconds. |
| statusUtcTime | Number | get scooter status info's UTC time. |
| signature | String | more info |
response
| field | type | description |
|---|---|---|
| message(optional) | String | - |
| code | Number | allowed: 0 |
HTTP/1.1 200 OK
{
“message”:success，
“code”: 0
}
# mech-lock status only for some mechanical locks
This API should be exposed by your application system to receive the status of mechanical lock.
POST
/v2/vehicle/mech-lock
https://business:port/v2/vehicle/mech-lock \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&statusUtcTime={tinmstamp}&status={0}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/x-www-form-urlencoded" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| platformCode | String | client_id |
| statusUtcTime | Number | timestamp |
| status | Number | 0→ mechanical lock pin is inserted |
| signature | String | more info |
response
| field | type | description |
|---|---|---|
| message(optional) | String | - |
| code | Number | allowed: 0 |
HTTP/1.1 200 OK
{
“message”:success，
“code”: 0
}
# components lock
This API should be exposed by your application system to receive the components status.
POST
/v2/vehicle/components
https://business:port/v2/vehicle/components \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&statusUtcTime={tinmstamp}&status={0}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/x-www-form-urlencoded" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| platformCode | String | client_id |
| type | Number | type: 8→helmet lock 9→steel cable lock |
| status | Number | operation status: 2→ lock. |
| statusUtcTime | Number | timestamp |
| signature | String | more info |
response
| field | type | description |
|---|---|---|
| message(optional) | String | - |
| code | Number | allowed: 0 |
HTTP/1.1 200 OK
{
“message”:success，
“code”: 0
}
# Appendix 1：Status code description
| sn | code | error |
|---|---|---|
| 1 | 15101 | token verification failed |
| 2 | 15100 | incorrect platform info |
| 3 | 15004 | parameter error |
| 4 | 15001 | server error |
| 5 | 15102 | device not found |
| 6 | 15300 | inactive device |
| 7 | 15301 | offline device |
| 8 | 15302 | device response timeout |
| 9 | 15303 | command send failed |
| 10 | 15400 | latest location not found via device |
| 11 | 15500 | device upgrading: command can not be executed |
| 12 | 15600 | lock failed: vehicle is riding |
| 13 | 15601 | device lock command failed |
| 14 | 15602 | device lock failed: network error |
| 15 | 15611 | device unlock command failed |
| 16 | 15612 | device unlock failed: network error |
# Appendix 2：Fault code list only for MaxPlus
| code | system | description |
|---|---|---|
| E0 | IoT | ECU communication error |
| E1 | IoT | Backup battery abnormality |
| E2 | IoT | RTC clock error |
| E3 | IoT | File system error |
| E4 | IoT | I2C communication error |
| E5 | IoT | GNSS communication error |
| E6 | IoT | 4G Modem communication error |
| E7 | IoT | Bluetooth communication error |
| E8 | IoT | NFC communication error |
| E9 | IoT | G-Sensor communication error |
| 10 | / | Abnormal communication between instrument panel and main control |
| 11 | motor | Abnormal A phase current sampling of the motor |
| 12 | motor | Abnormal B phase current sampling of the motor |
| 13 | motor | Abnormal C phase current sampling of the motor |
| 14 | / | Abnormal accelerator Hall |
| 15 | / | Abnormal left brake Hall |
| 16 | / | Abnormal right brake Hall, this error only would occur on MAX 2.3 plus |
| 17 | / | Undefined |
| 18 | / | Abnormal motor Hall |
| 19 | BMS | Battery abnormality in voltage detection |
| 20 | / | Undefined |
| 21 | BMS | Battery abnormality in communication |
| 22 | BMS | Battery password is wrong |
| 23 | BMS | Battery is in default serial number |
| 24 | ECU | System voltage detection abnormality |
| 25 | ECU | Undefined |
| 26 | ECU | Flash save error |
| 27 | ECU | Master control password is wrong |
| 28 | / | Undefined |
| 29 | / | Undefined |
| 30 | / | Undefined |
| 31 | / | Program skip error |
| 32 | / | IOT and scooter communication timeout error |
| 33 | / | Undefined |
| 34 | / | Undefined |
| 35 | / | Vehicle is in default serial number |
| 36 | / | Undefined |
| 37 | / | Charging base failure or battery charging wire failure |
| 38 | / | Undefined |
| 39 | / | Battery temperature sensor abnormality |
| 40 | / | Controller temperature sensor abnormality |
| 41 | / | Over temperature of motor |
| 50 | / | Verfication between battery and controller failed |
| 51 | / | Main controller and goose head doesn’t match with each other |
| 52 | / | The identify code of main controller is not matched with swappable battery lock |
| 54 | / | The communication status between main controller and swappable |