MaaS API definition (0.0.1)

Download OpenAPI specification:

Introduction

Knot MaaS API is an implementation of Instant System's APIs. This API allow a MaaS provider to integrate its solution with Knot, allowing to use Knot kick-scooter through others applications. An API Key is required, please contact us to get one.

Available features

The following features are implemented:

OAuth 2 login
Get stations list
Get a station
Get stations statuses
Get vehicles list
Get a vehicle
Get user bookings list
Get a specific booking
Start an instant usage
Estimate price
User management

Current limitations

There is no reservation for the moment. The billing / payment isn't implemented yet, so only a usage for free user (for example when a organization pay the usage for its employee) can be done through this API.

Booking

List user's bookings

Return past and ongoing user's bookings.

Authorizations:

(MaasApiKeyMaaSAuthenticated)

query Parameters

minStartDate	string <date-time>
maxStartDate	string <date-time>
state	string Enum: "ONGOING" "PAST"

Responses

Response samples

200
400
401
500

Content type

application/json

{"bookingInformations": [{"id": "string",
"status": "FUTURE",
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"startLocation": {"lat": 45.18,
"lon": 5.23
},
"endLocation": {"lat": 45.18,
"lon": 5.23
},
"vehicle": {"id": "254",
"name": "ARV005",
"type": "KICK_SCOOTER"
},
"actions": [{"type": "RETURN_VEHICLE"
}
],
"price": {"amount": 0,
"vat": 0,
"currencyCode": "string"
}
}
]
}

Get specific booking

Return the specified user booking.

Authorizations:

(MaasApiKeyMaaSAuthenticated)

path Parameters

id

required

string

Example: 235

Identifier of the booking.

Responses

Response samples

200
400
401
404
500

Content type

application/json

{"bookingInformations": {"id": "string",
"status": "FUTURE",
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"startLocation": {"lat": 45.18,
"lon": 5.23
},
"endLocation": {"lat": 45.18,
"lon": 5.23
},
"vehicle": {"id": "254",
"name": "ARV005",
"type": "KICK_SCOOTER"
},
"actions": [{"type": "RETURN_VEHICLE"
}
],
"price": {"amount": 0,
"vat": 0,
"currencyCode": "string"
}
}
}

Instant Usage

Starts the usage of this mobility service by unlocking the vehicle.

Authorizations:

(MaasApiKeyMaaSAuthenticated)

header Parameters

x-maaspro-profile

string

Enum: "pro" "personal"

Request Body schema: application/json

lat	string User's current latitude.
lon	string User's current longitude.
vehicle	string This is the vehicle identifier, which can come from several mechanisms: Raw content of a QrCode read in a kick-scooter, serial name (written on the kick-scooter) typed by the user or the vehicle identifier.

Responses

Request samples

Payload

Content type

application/json

{"lat": "string",
"lon": "string",
"vehicle": "string"
}

Response samples

Content type

application/json

{"bookingInformations": {"id": "string",
"status": "FUTURE",
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"startLocation": {"lat": 45.18,
"lon": 5.23
},
"endLocation": {"lat": 45.18,
"lon": 5.23
},
"vehicle": {"id": "254",
"name": "ARV005",
"type": "KICK_SCOOTER"
},
"actions": [{"type": "RETURN_VEHICLE"
}
],
"price": {"amount": 0,
"vat": 0,
"currencyCode": "string"
}
}
}

Price estimation

Estimate price

Estimate the price of a rent with the specified argument.

Authorizations:

(MaasApiKeyMaaSAuthenticated)

Request Body schema: application/json

required	object Geographical location of the start place.
required	object Geographical location of the arrival place.
startDate required	string <date-time> Start date time of the mobility usage (ISO 8601).
endDate required	string <date-time> End date time of the mobility usage (ISO 8601).
required	object Vehicle considered for the estimation.

Responses

Request samples

Payload

Content type

application/json

{"startLocation": {"lat": 45.18,
"lon": 5.23
},
"endLocation": {"lat": 45.18,
"lon": 5.23
},
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"vehicle": {"id": "254"
}
}

Response samples

200
400
401
500

Content type

application/json

{"price": {"EstimatedAmount": 487,
"minAmount": 487,
"maxAmount": 587,
"currencyCode": "string"
}
}

Stations

Stations statuses

This service provides the real time status of the stations for station-based vehicle fleet.

Authorizations:

MaasApiKey

Responses

Response samples

200
401
500

Content type

application/json

{"stationsStatus": [{"id": "400",
"numVehiclesAvailable": 12,
"numVehiclesDisabled": 0,
"numDocksAvailable": 10,
"numDocksDisabled": 0,
"isInstalled": true,
"isRenting": true,
"isReturning": true
}
]
}

Stations list

This service provides the static list of stations for station-based vehicle fleet.

Authorizations:

MaasApiKey

Responses

Response samples

200
401
500

Content type

application/json

{"stations": [{"id": "400",
"name": "Arval siège",
"location": {"lat": 45.18,
"lon": 5.23
},
"capacity": 8
}
]
}

Station by id

This service provides the details of a station.

Authorizations:

MaasApiKey

path Parameters

id

required

string

Example: 235

Identifier of the station.

Responses

Response samples

200
401
500

Content type

application/json

{"stations": {"id": "400",
"name": "Arval siège",
"location": {"lat": 45.18,
"lon": 5.23
},
"capacity": 8
}
}

Users

Create user

Create a MaaS user. The only way for this user to login is through the MaaS API.

Authorizations:

MaasApiKey

Request Body schema: application/json

id	string [ 1 .. 128 ] characters An identifier for this user. If not provided one is automatically generated and returned.
email required	string <email> The email of the user, it should be valid as mails can be send for legal purposes.
firstName required	string [ 1 .. 50 ] characters First name of the user.
lastName required	string [ 1 .. 50 ] characters Last name of the user.
phone	string [ 1 .. 20 ] characters ^\+\d{1,4} ?\d{3,14}$ Phone number of the user, not used for communication but allows to reduce fraud.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Response samples

200
400
401
500

Content type

application/json

{"code": 0,
"id": "string",
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string",
"accessToken": "string",
"refreshToken": "string",
"expiresIn": 0
}

Get user

Get a MaaS user.

Authorizations:

MaasApiKey

path Parameters

userId

required

string [ 1 .. 128 ] characters

Identifier of the user.

Responses

Response samples

200
400
401
500

Content type

application/json

{"code": 0,
"id": "string",
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string",
"accessToken": "string",
"refreshToken": "string",
"expiresIn": 0
}

Update user

Update a MaaS user info.

Authorizations:

MaasApiKey

path Parameters

userId

required

string [ 1 .. 128 ] characters

Identifier of the user.

Request Body schema: application/json

email	string <email> The email of the user, it should be valid as mails can be send for legal purposes.
firstName	string [ 1 .. 50 ] characters First name of the user.
lastName	string [ 1 .. 50 ] characters Last name of the user.
phone	string [ 1 .. 20 ] characters ^\+\d{1,4} ?\d{3,14}$ Phone number of the user, not used for communication but allows to reduce fraud.

Responses

Request samples

Payload

Content type

application/json

{"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Response samples

200
400
401
500

Content type

application/json

{"code": 0,
"id": "string",
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string",
"accessToken": "string",
"refreshToken": "string",
"expiresIn": 0
}

Delete user

Delete a MaaS user.

Authorizations:

MaasApiKey

path Parameters

userId

required

string [ 1 .. 128 ] characters

Identifier of the user.

Responses

Response samples

200
400
401
500

Content type

application/json

{"code": 0
}

Get my info

Get the requesting MaaS user's info.

Authorizations:

(MaasApiKeyMaaSAuthenticated)

Responses

Response samples

200
400
401
500

Content type

application/json

{"code": 0,
"id": "string",
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Update my info

Update a requesting MaaS user info.

Authorizations:

(MaasApiKeyMaaSAuthenticated)

Request Body schema: application/json

email	string <email> The email of the user, it should be valid as mails can be send for legal purposes.
firstName	string [ 1 .. 50 ] characters First name of the user.
lastName	string [ 1 .. 50 ] characters Last name of the user.
phone	string [ 1 .. 20 ] characters ^\+\d{1,4} ?\d{3,14}$ Phone number of the user, not used for communication but allows to reduce fraud.

Responses

Request samples

Payload

Content type

application/json

{"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Response samples

200
400
401
500

Content type

application/json

{"code": 0,
"id": "string",
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Vehicles

Vehicles list

This service provides the real time list of vehicles (free-floating and station-based).

Authorizations:

MaasApiKey

Responses

Response samples

200
401
500

Content type

application/json

{"vehicles": [{"id": "254",
"name": "ARV005",
"type": "KICK_SCOOTER",
"location": {"lat": 45.18,
"lon": 5.23
},
"stationId": 0,
"dockId": 1,
"status": "DISABLED",
"engine": {"batteryLevel": 95,
"autonomy": 30
},
"model": "Ninebot ES2"
}
]
}

Vehicle by id

This service provides info about a vehicle.

Authorizations:

MaasApiKey

path Parameters

id

required

integer >= 1

Identifier of the vehicle.

Responses

Response samples

200
401
500

Content type

application/json

{"vehicles": {"id": "254",
"name": "ARV005",
"type": "KICK_SCOOTER",
"location": {"lat": 45.18,
"lon": 5.23
},
"stationId": 0,
"dockId": 1,
"status": "DISABLED",
"engine": {"batteryLevel": 95,
"autonomy": 30
},
"model": "Ninebot ES2"
}
}