# Segway API-ES

Welcome to the Segway API of Gateway. This API reference provides information on endpoints available 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:m, so 1230 means 1.23km)
remainingRange Number remaining range (unit: 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"
}

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

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

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

# transportation mode common for scooters(ES,Max,MaxPro,MaxPlus)

This API is used to set the vehicle into the transportation mode in which it will be powered off and in offline state. We recommend using this command when the scooter won't be used and will be kept in the warehouse for a long time.

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

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 >= 151
buzzer(optional) Number 0→ no setting 1→off. 2→on
Note: IoT version should >= 152

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 speed range: 6-25. unit:km/h
mediumSpeedLimit(optional) Number speed range: 6-25. unit:km/h
highSpeedLimit(optional) Number speed 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"
}

# sound setting

This API is used to set relevant parameters of the sound.

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 '{

}'

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
sctoMask(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 >= 152

attached:'sctoMask'

field type description
powerOn (optional) Number 0:disable 1:enable 2:keep original
powerOff (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
lostHeartbeat (optional) Number 0:disable 1:enable 2:keep original
outofGeofence (optional) Number 0:disable 1:enable 2:keep original
intoGeofence (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"
}

# 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 >= 152, 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"
}

# 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.
6->vehicle was lifted up.

available disappeared alert code:
1->illegal moving.
2->vehicle fell down.
3->illegal dismantling.
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 unlocked, 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
}

# 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 common for scooters(ES,Max,MaxPro)

code system description
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