# Segway API-T60 Lite

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

This API is used to get a token for other APIs.

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

# Control

# unlock

This API is used to unlock the vehicle.

POST

/api/v2/vehicle/control/t60/unlock

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/t60/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 15704 the device is in dormancy
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# lock

This API is used to lock the vehicle.

POST

/api/v2/vehicle/control/t60/lock

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/t60/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 15704 the device is in dormancy
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# headlight

This API is used to turn the vehicle's headlight on or off. ONLY available in unlock state.

POST

/api/v2/vehicle/control/t60/headlight

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/t60/headlight \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "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 String 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
10 15709 the device is not in unlock state
11 15704 the device is in dormancy
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# speedlimit

This API is used to set speed limit for the device.

POST

/api/v2/vehicle/control/robot-speed-limit

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/robot-speed-limit \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116",
    "speed" : 200
}'

Header

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

Parameter

field type description
iotCode String IoT IMEI
speed Number speed limit range: [100,700] (cm/s)

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 15709 the device is not in unlock state
11 15704 the device is in dormancy
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# throttle response

This API is used to turn the vehicle's throttle response on/off.

POST

/api/v2/vehicle/control/t60/throttle-response

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/t60/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 String 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
10 15704 the device is in dormancy
11 15705 throttle control failed
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# alarm on/off

This API is used to turn the vehicle's alarm trigger on/off.

POST

/api/v2/vehicle/control/robot-alarm

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/robot-alarm \
--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 String 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
10 15704 the device is in dormancy
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 compartment.

POST

/api/v2/vehicle/control/t60/battery-cover

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/t60/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 15704 the device is in dormancy
11 15706 battery cover control failed
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# reboot

This API is used to reboot the scooter.

POST

/api/v2/vehicle/control/reboot

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/reboot \
--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 15704 the device is in dormancy
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# shutdown

This API is used to make the scooter power off. ONLY available in lock state.

POST

/api/v2/vehicle/control/shutdown

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/shutdown \
--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 15704 the device is in dormancy
12 15708 the device is not in lock state
HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

# AI-switch

This API is used to turn the vehicle's AI-switch on or off.

POST

/api/v2/vehicle/control/ai-switch

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/ai-switch \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116",
    "switchType": 1,
    "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
switchType Number the type of AI switch
1->pedestrian detection
2->sidewalk detection
3->parking space detection
4->cycle path detection
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
10 15704 the device is in dormancy
11 15639 the device is maintaining
12 15640 command execute failed
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 location

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/t60/location

curl -X POST \
https://business:port/v2/vehicle/t60/location \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&signature={signature}&locationStatus={locationStatus} \
&latitude={latitude}&longitude={longitude}&gpsSignal={gpsSignal}&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 -
locationStatus String allowed: 'invalid' and 'valid'
latitude Double latitude (WGS84).
longitude Double longitude (WGS84).
gpsSignal Double 0 unknown; 1 strong; 2 normal; 3 weak
Allowed values: 0, 1, 2,3
gpsUtcTime Long timestamp
signature String more info

response

field type description
message(optional) Boolean -
code Number allowed: 0
HTTP/1.1 200 OK
{        
        “message”:success,
        “code”: 0
}

# vehicle status

This API should be exposed by your application system to receive the changes of the scooter's status.

POST

/v2/vehicle/t60/status

curl -X POST \
https://business:port/v2/vehicle/t60/status \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&signature={signature}&online={online}&locked={locked} \
&networkSignal={networkSignal}&charging={charging}&powerPercent={powerPercent} \
&speed={speed}&odometer={odometer}&odometer={odometer}&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 -
online Boolean true→ connected to SEGWAY Cloud. false→ disconnected
lock Integer 1→ lock. 0→unlock
networkSignal Integer 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 Integer battery percentage, 80->80%.
speed Integer scooter current speed.
odometer Double total odometer (unit is 1m, so 1230 means 1.23km
statusUtcTime Long get scooter status info's UTC time.
signature String more info

response

field type description
message(optional) Boolean -
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
17 15701 the device is unlocked
19 15703 wrong state
20 15704 the device is in dormancy
21 15705 throttle control failed
22 15706 battery cover control failed
23 15639 the device is maintaining
24 15640 command execute failed