# Segway API-E-bike A200

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(Exercise) ; 2: medium speed(Eco) ; 3: high speed (Turbo) ;
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 E-bike C80, E-bike A200 and E-moped

This API is used to get the Mopeds battery information.

GET

/api/v2/mopeds/query/current/battery-info

curl -X GET \
https://api_domain:port/api/v2/mopeds/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
vehiclePercent Number battery percent, unit:80->80%
batteryCount Number count: 1~3
drivingVoltage Number unit: 80->80V
currentPower Number current power of vehicle, unit: W
iotPercent Number iot battery percent, unit:80->80%
iotVoltage Number current voltage of IoT: 411->4.11V
batteryData list Object list: 'battery data'

attached:'battery data'

field type description
batteryPort Number allowed: 1,2,3
batteryPercent Number batterypercent, unit/80->80%
batteryVoltage Number battery voltage,40->40V
cycleTimes Number cycleTimes
temperatrue Number temperatrue1, unit/℃
HTTP/1.1 200 OK
{
	"code": 0,
	"msg": "success",
	"data": {
		"iotCode": "{iotCode}",
		"charging": true,
		"vehiclePercent": 80,
		"batteryCount": 2,
		"drivingVoltage": 80,
		"currentPower": 260,
		"iotPercent": 100,
		"iotVoltage": 412,
		"batteryData": [{
				"batteryPort": 1,
                "batteryPercent": 52,
                "batteryVoltage": 48,
				"cycleTimes": 23,
				"temperatrue": 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"
}

# 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 15613 handlebar unlock failed
13 15614 Mech-Lock unlock false throttle is on
14 15613 Mech-Lock unlock false
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# battery component

This API is used to open the battery components.

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
10 15635 open failed: please operate when mopeds is unlocking
11 15638 device execute failure
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 2→sound2(toot)
10→custom sound1
11→custom sound2
12→custom sound3
13→custom sound4

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.

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
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# anti-theft

The anti-theft alarm is enabled when the vehicle is unlocked by default. This function is used to turn off/on the anti-theft alarm when the vehicle is unlocked so that our operator can move them form one place to another one.

POST

/api/v2/vehicle/control/anti-theft

curl -X GET \
https://api_domain:port/api/v2/vehicle/control/anti-theft \
--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
controlType Number used to turn off/on the anti-theft alarm 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 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"
}

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

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 1:Low 2:Medium 3:High
mode Number 0:Auto 2:Always on 3:Blinking 4:Breathing
color Number 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet 7:White

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"
}

# wireless charging

Wireless charging for mobile phones is enabled when the vehicle is unlocked by default. Through this interface you can turn it off if you want to close this function during this unlocking period.

POST

/api/v2/vehicle/control/wireless-charging

curl -X GET \
https://api_domain:port/api/v2/vehicle/control/wireless-charging \
--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
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 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

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"
}

# Setting

# switch setting only for E-bike A200

This API is used to turn on or off the switch.

POST

/api/v2/ebike/setting/switch

curl -X POST \
https://api_domain:port/api/v2/ebike/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
bssDisplay Number displayed as bbs(British Standard speed)
0→ no setting 1→off. 2→on
alertSensitivity Number strength range: 1-3
unlockHeadLight Number used to enable or disable the headLight when device is unlocked
0→ no setting 1→off. 2→on
unlockTailLight Number used to enable or disable the tailLight when device is unlocked
0→ no setting 1→off. 2→on 3->flicker
brakeTailLight Number used to enable or disable the tailLight when the brake is holded
0→ no setting 1→off. 2→on 3->flicker
wirelessCharge Number used to enable or disable the wireless charge when device is unlocked
0→ no setting 1→off. 2→on
climbInput Number used to enhance the output power when Ebike is climbing
0→ no setting 1→off. 2→on
speedLimit(optional) Number size range: 6-32. unit:km/h
lowPowerValue(optional) Number The vehicle will upload the prompt if the vehicle percent is less than lowPowerValue
range: 0-30 , 0 means Disabled. default:5

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.

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": 3,
    "exerciseMode": {
        "mode": 4,   /* 4:breathing */
        "bright": 2, /* 2:Medium */
        "color": 1   /* 1:Green */
    },
    "faultMode": {
        "mode": 2,   /* 2:Always on */
        "color": 2   /* 1:Red */
    }
}'

Header

field type description
Content-Type String allowed: "application/json"
Authorization String allowed: "bearer access_token"

Parameter

field type description
iotCode String IoT IMEI
brightrequired Number Common atmosphere lamp brightness of each mode.
1:Low 2:Medium 3:High
lockedMode(optional) Object An object that indicates the atmosphere lamp effect
faultMode(optional) Object An object that indicates the atmosphere lamp effect
exerciseMode(optional) Object An object that indicates the atmosphere lamp effect
ecoMode(optional) Object An object that indicates the atmosphere lamp effect
turboMode(optional) Object An object that indicates the atmosphere lamp effect

attached:'lockedMode,faultMode,exerciseMode,ecoMode,turboMode'

field type description
mode Number 1:Off 2:Always on 3:Blinking 4:Breathing
bright(optional) Number The atmosphere lamp brightness of this particular mode.
1:Low 2:Medium 3:High
color Number 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet 7:White

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.

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

attached:'ebaqMask'

field type description
locked (optional) Number 0:disable 1:enable 2:keep original
unlocked (optional) Number 0:disable 1:enable 2:keep original
batteryOn (optional) Number 0:disable 1:enable 2:keep original
illegalMoving (optional) Number 0:disable 1:enable 2:keep original
fault (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
modeSwitch (optional) Number 0:disable 1:enable 2:keep original
nfcReadSuccess (optional) Number 0:disable 1:enable 2:keep original
nfcReadFailed (optional) Number 0:disable 1:enable 2:keep original
batteryCoverUnlocked (optional) Number 0:disable 1:enable 2:keep original
batteryCoverLocked (optional) Number 0:disable 1:enable 2:keep original
fullyCharged (optional) Number 0:disable 1:enable 2:keep original
cableLocked (optional) Number 0:disable 1:enable 2:keep original
cusAudio01 (optional) Number 0:disable 1:enable 2:keep original
cusAudio02 (optional) Number 0:disable 1:enable 2:keep original
cusAudio03 (optional) Number 0:disable 1:enable 2:keep original
cusAudio04 (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
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# speed mode

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(Exercise). 2→ medium speed(Eco). 3→high speed(Turbo)

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

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"
}

# 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.
12->low power

available disappeared alert code:
1->illegal moving.
2->vehicle fell down.
3->illegal dismantling.
12->low power
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 vehicle is unlocked, its location will be pushed once every 10 seconds. When the vehicle 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 Mopeds status. When the Mopeds 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(Exercise); 2: medium speed(Eco); 3: high speed(Turbo) ;
speed Number Mopeds 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 Mopeds 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
}

# 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:
5→ mechanical lock and electric 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

code error
15101 token verification failed
15100 incorrect platform info
15004 parameter error
15001 server error
15102 device not found
15103 iot not unmatched platform
15104 please wait until the last request has it's response
15300 inactive device
15301 offline device
15302 device response timeout
15303 command send failed
15305 device update message is invalid
15304 IoT is not binding to the vehicle
15400 latest location not found via device
15500 device upgrading: command can not be executed
15600 lock failed: vehicle is riding
15601 device lock command failed
15602 device lock failed: network error
15603 bike has been used
15611 device unlock command failed
15612 device unlock failed: network error
15614 Mech-Lock unlock false throttle is on
15613 Mech-Lock unlock false
15704 the device is in dormancy
15701 the device is unlocked
15702 the device is not in teleoperation mode
15705 This feature is not supported on the vehicle
15706 This command is not supported in the current mode
15620 startRental failed
15621 startRental failed: network error
15622 startRental failed: handlebar failed
15623 startRental success, but open saddle failed
15624 startRental success, but open tailbox failed
15625 startRental success, but tailbox and saddle failed
15627 endRental failed: vehicle is riding
15628 endRental failed
15629 endRental: network error
15630 endRental failed: handlebar lock failed
15631 endRental failed: no return helmet
15632 endRental failed: saddle lock failed
15633 endRental failed: tailbox lock failed
15634 endRental failed: tailbox and saddle lock failed
15635 open failed, please operate when mopeds is unlocking
15636 handlebar lock failed
15637 handlebar unlock failed
15638 device execute failure

# Appendix 2:Fault code list only for E-bike A200

code description
E0 ECU communication error
E1 Backup battery abnormality
E2 RTC clock error
E3 File system error
E4 I2C communication error
E5 GNSS communication error
E6 4G Modem communication error
E7 Bluetooth communication error
E8 NFC communication error
E9 G-Sensor communication error
10 Communication error between the controller and dashboard, please check the controller, the dashboard and the connecting cables.
11 Motor A phase current error. Please check the motor controller.
12 Motor B phase current error. Please check the motor controller.
13 Motor C phase current error. Please check the motor controller.
14 Throttle Hall sensor error. Please check the throttle handle, dashboard and the connecting cables.
15 Brake switch 1 error. Please check the brake lever, dashboard and the connecting cables.
16 Brake switch 2 error. Please check the brake lever, dashboard and the connecting cables.
17 Reserved
18 Motor Hall sensor error, please check the motor, the motor controller and the connecting cables.
19 Abnormal Lithium battery voltage detection. Please check the battery, motor controller and the connecting cables.
20 Lithium battery has the default serial number, please confirm whether it is a genuine battery.
21 Lithium battery communication error, please check dashboard, battery and the connecting cables.
22 Lithium battery password error, please confirm whether it is a genuine battery.
23 Lithium battery discharging MOS temperature error, please check the battery.
24 Lithium battery cells temperature error, please check the battery.
25 Lithium battery charging MOS temperature error, please check the battery.
26 BMS communication error, please confirm whether it is a genuine battery.
27 Flash save error. Please check motor controller.
28 The dashboard displays PN code by default, please confirm whether it is a genuine vehicle.
29 The repeater displays PN code by default, please confirm whether it is a genuine vehicle.
30 The vehicle has the defaut serial number, please confirm whether it is a genuine vehicle.
31 Vehicle password error, please confirm whether it is a genuine vehicle.
32 Reserved
33 Abnormal controller temperature detection, please check the controller.
34 Abnormal motor temperature detection, please check the motor.
35 Posture sensor communication error
36 Gyroscope data error
37 Reserved
38 Torque sensor error
39 Reserved
40 Velocity sensor error
41 Battery-cover lock communication error
42 ECU (Electronic Control Unit) doesn't match the battery-cover lock ID
43 Battery-cover unlock error
44 Monitoring chip communication error
60 IoT communication timeout error
61 IoT encrypted communication error