MaaS API definition (0.0.1)

Download OpenAPI specification:Download

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 stations statuses
Get vehicles list
Get user bookings list
Get a specific booking
Start an instant usage
Estimate price

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.

Authentication

MaasApiKey

All API call should be done using your API Key.

Security Scheme Type	API Key
Header parameter name:	x-api-key

MaaSAuthenticated

Required for user specific operation. Request should be made with a authentication token provided by the Oauth login.

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

Booking

List user's bookings

Return past and ongoing user's bookings.

Authorizations:

MaasApiKey

MaaSAuthenticated

query Parameters

minStartDate	string <date-time>
maxStartDate	string <date-time>

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:

MaasApiKey

MaaSAuthenticated

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:

MaasApiKey

MaaSAuthenticated

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

201
400
401
404
500

Content type

application/json

{"bookingInformation": {"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"
}
}
}

Stations

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

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

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

Price estimation

Estimate price

Estimate the price of a rent with the specified argument.

Authorizations:

MaasApiKey

MaaSAuthenticated

Request Body schema: application/json

required	object (Location)
required	object (Location)
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"
}
}