Introduction
In this guide, the goal is to give an insight into the goUrban environment as well as describe the usage of the goUrban MaaS API. This comes along with some basics to get started as well as very specific concepts and technical flows describing how the interaction with the environment works to achieve the desired outcome.
MaaS is the integration of various forms of transport services into a single mobility service, accessible on demand. For the user, MaaS offers added value through the use of a single application to provide access to mobility, with a single payment channel instead of multiple ticketing and payment operations.
To meet a customer’s request, a MaaS operator facilitates a diverse menu of transport options, be they public transport, ride-, car- or bike-sharing, taxi, car rental or lease, or a combination thereof.
A successful MaaS service also brings new business models and ways to organize and operate the various transport options, with advantages including access to improved user and demand information and new opportunities to serve unmet demand for transport operators.
The aim of MaaS is to be the best value proposition for its users that may be as convenient, more sustainable, and even cheaper as the user of a private car while contributing to the achievement of societal and environmental goals.
goUrban
goUrban is accelerating the transition to mobility as a service by offering the most powerful operating system for shared mobility. We have built enterprise tools to help solve the operator’s challenges around operations, maintenance, customer support, marketing activities, business insights, accounting, controlling, and access for city governments to comply with public regulations. Furthermore, we help connect their vehicles and offer optional white-label mobile applications for maintenance in the field and for the operator’s end-users. This drives us to become the world-wide largest operating system to empower operators to design the mobility of tomorrow.
MaaS API (Impersonation API)
The goUrban MaaS (Impersonation) API is a top-level API allowing authorized API users to impersonate other end-users for use cases like MaaS applications. This makes it possible to work with one API client when it comes down to authorization and still has the benefit of correct action traceability of specific users as well as correct analytics based on demographic as well as other factors.
Documentation: https://user-api.docs.gourban.co/
Example Use-case:
A MaaS application would like to fetch vehicles and all other relevant fleet management information and reserve and rent vehicles of a goUrban client. To achieve this the MaaS application requests an API user access from goUrban via the corresponding client and authorizes its' user to use the MaaS API. Having the token at hand this API client is able to fetch vehicles, branches, and alike and create users in the goUrban environment on the fly and connect this user to the own platform for further reference and impersonation. Once the user is created this user can be impersonated using the impersonation header of this API. Impersonation is possible for rentals and all other relevant actions of an end user.
Getting started
To get started in the goUrban landscape dig into our knowledge base and make yourself familiar with the terminology and the fundamental concepts used in the environment.
Flows
Before digging deeper into the specifics of this very API usage feel free to check the API Basics which are relevant for all of the goUrban APIs.
Impersonation header (pass UUID of goUrban user)
The MaaS API extends the user API by providing a way to request resources on behalf of another user. This frees the application from the need to store the credentials for each user and manage a separate pair of access and refresh tokens for each user.
Impersonation is done by including the user identifier (UUID) on which behalf the resource should be accessed as HTTP header "GoUrban-Impersonate" (subject to change).
The API client which accesses the resources needs to have permission for impersonation. Only users which have been created by this API client can be impersonated by the same API client. This is to prevent misuse and accidentally impersonating a user who was created through the normal sign-up flow.
Sequence diagram:
Simple Rental Flow
Authorization
Login with the given API Client credentials and store the received access token and refresh token for all future calls. Details on the authorization and how to handle the tokens are described on the API Basics page.
User Creation
Create a new MaaS user providing a minimum
- firstName, lastName, birthDate - details of the user to be created
- branchId - determines the country the user will be able to make rentals in (determined with branch resolver, for initial setup provided by goUrban)
Further information might be required depending on the way the system is configured (Check with the operator concerning rental requirements to find out which). This will return a newly created user object which includes the impersonateUuid which can be used on further requests to interact with goUrban API on behalf of this user.
General Information endpoints:
- branches - provides information about all branches this user currently has access to.
- vehicle categories - provides information about all available (or non-available) vehicle types within the system. This information should be cached and used when retrieving a vehicle and cross-referencing its vehicle_category_id
Vehicles
Retrieve vehicles that are available to the impersonated user. The vehicle objects of the returned list should include all required information to display a vehicle on a map. For more details use the getVehicleById endpoint. This result will also include the standard pricing and any discounts that might be applied to the vehicle.
Terms & Conditions
Every branch can have its own definition of T&C and to interact with a vehicle of a branch the user must have accepted the latest T&C.
If you encounter an error with code U601 or U602 this means you, the user still, needs to accept the T&C. To do this, first determine which T&C need to be accepted for a vehicle or a branch, show the T&C to the user and if they accept them, then trigger a request to accept the T&C.
Rental
In the goUrban environment, a ride or trip with a vehicle is defined as a rental.
A vehicle can be used by either reserving it before starting a rental or directly renting it. A rental can be started by either using the vehicle code, e.g. by QR code scan, or vehicle-id by selecting it on a digital map of previously fetched vehicles.
Creation: When creating a rental the following fields are required:
- startRentalState - RESERVATION reserves the vehicle for a time, or ACTIVE turns on the vehicle and starts the paid time.
- vehicleCode or vehicleId - defines the vehicle that is to be used
- userGroupCode - defines the balance that should be used for billing this ride (provided by goUrban)
- further fields are available like additions or paidReservationMinutes but are not necessary for the most basic use
Interaction: The rental object can then be interacted with by issuing different rentalOperations
- START - Take a rental from state RESERVATION into state ACTIVE, this will turn the vehicle on and start the billed time.
- END - Stop a rental. This will turn the vehicle off and end the billed time.
- PARK - Switch a rental into PARKING mode. This will turn the vehicle off but not stop the billed time. The vehicle is still under the users control and can’t be taken by someone else.
- DRIVE - Switch from PARKING back into DRIVING mode. The vehicle will turn on
- OPEN_TAILBOX - Opens the helmet compartment of a vehicle. (This operation is only supported by some vehicle types)
Ending: To end a rental you provide the above-mentioned END operation on the rentalOperations endpoint. This will check if all preconditions for the ending are met (e.g. vehicle is within a business area) and then turn off the vehicle and calculate the final price. If not all preconditions are met, the system will respond with an error and a comprehensive error message. If it is successful, the response will contain the Rental object including the final price, kilometers, and times.
When ending the rental further information can be provided:
- Upload a picture of the parked vehicle and provide the returned file-id in the rentalOperation request
- (optional) Feedback: The finished rental can be patched with feedback tags and a rating between 1-5 stars.
The most common errors that can happen when creating a rental can be found in the Error Codes starting with the letters R and V. Some of the most common ones are:
- Double-clicking: R102 - you've already got an active rental.
Solution: Loading indicator while the process is ongoing. - Vehicle Communication issues: R170 - communication failure with the vehicle during the reservation of rental.
Solution: Retry the operation as the vehicle might have a bad reception. - Business area violation: R131 - rental must be ended inside the business area. Solution: Move the vehicle inside of the business area and retry.
Other Flows
- Determine home country: Resolve the closest branch to the MaaS user’s device location and store it for branch-dependent API endpoints.
- Branches: Fetch all the branches and show the connected areas and stations if applicable. More details on what the areas signify and how they are differentiated can be found in the fundamentals in the knowledge base Types of branches Business area
- Promotions: Apart from the business-, prohibited-, and restricted areas there is also geo-fence promotion areas. Those can be fetched using the Promotions API and return areas where rentals received a discount. There we differentiate between areas where the user gets a percentage discount when starting, ending a rental or both.
- Vehicles: Fetch all the vehicles and find attached flags stating whether they are promoted or not. Promoted vehicles will have some discount on finished rentals due to geo-fence promotions stated above. Only vehicles located inside a START_RENTAL geo-fence promotion area will have that flag set to true. To keep the vehicles up to date this call has to happen in a scheduled manner.
Entire User Journey
Error Codes
Find a list of error codes in the document below: