Taxi API -service documentation

1 (10)

[LUONNOS/DRAFT]

22.12.2015

Taxi API -service documentation [LUONNOS/DRAFT] 22.12.2015

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

2 (10)

[LUONNOS/DRAFT]

22.12.2015

Index 1.Introduction........................................................................................................................................ 3 1.1. Overview..................................................................................................................................................... 3 1.2. Purpose....................................................................................................................................................... 3 1.3. Abbreviations.............................................................................................................................................. 3

2. Mobility as a Service -operator requirements....................................................................................4 2.1. Contracts..................................................................................................................................................... 4 2.1.1 Basic level of contract for ordering taxis............................................................................................................................................4 2.1.2 Professional level of contract for ordering prepaid taxis....................................................................................................................4 2.2 Common requirements for MaaS-operator...........................................................................................................................................5

3. Use cases......................................................................................................................................... 6 3.1. Basic use case: Ordering a Taxi - Ad-hoc................................................................................................... 6 3.1.1. Overview............................................................................................................................................................................................6 3.1.2. Needed interfaces (Sequence diagram for ordering a taxi ad-hoc) .................................................................................................6 3.1.3 Notes..................................................................................................................................................................................................6

3.2. Basic use case: Pre ordering a Taxi at specific time...................................................................................6 3.2.1. Overview............................................................................................................................................................................................6 3.2.2. Needed interfaces (Sequence diagram for pre ordering a taxi)........................................................................................................7 3.2.3 Notes..................................................................................................................................................................................................7

3.3. Complex use case: Taxi sharing - Ordering a Taxi for a group of people from/to multiple locations............8 3.3.1. Overview............................................................................................................................................................................................8 3.3.2. Needed interfaces (Sequence diagram for ordering a taxisharing)..................................................................................................8 3.3.3 Notes..................................................................................................................................................................................................8

3.4 Common use cases related to MaaS-operator order management using Taxi API......................................9 3.4.1 Current status for orders....................................................................................................................................................................9 3.4.2 Cancel an order................................................................................................................................................................................10

4. Technical interface specification......................................................................................................10 5. Other............................................................................................................................................... 10 5.1 Contact information.................................................................................................................................... 10 5.2 Help and Assistance.................................................................................................................................. 10

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

3 (10)

[LUONNOS/DRAFT]

22.12.2015

1.Introduction This document is to describe how Mobility as a Service (MaaS) service providers can use Taxi application programming interface (Taxi API) of Taksiliiton Yrityspalvelut Oy (TYP) to enable taxi services in their MaaS service concepts.

1.1. Overview Taksiliiton Yrityspalvelut Oy (TYP) provides an application programming interface (API) to its existing national taxi system by which all local taxi dispatching centers are integrated to be available for 3rd parties (e.g. MaaS service providers). API is implemented as a REST/JSON interface, where users of the interface can inquire, book, change and cancel taxi rides for an individual taxi user or even for combined taxi ride for several individual taxi users. Also some additional features for information exchange are available to support service concepts e.g. by additional taxi ride information.

1.2. Purpose This document aims to give all the relevant information and guidance to integrate Finnish taxi services to MaaS service concepts in Finland. Thus, any 3rd party contracted by TYP to use the API can merge taxis to their service concepts. This document includes technical details to facilitate the use of the API. Any contractual issue related to the use of the API are to be managed by TYP representatives. Help and Assistance -section provides contact details in case of further assistance is required. The development and implementation of Taxi API is part of TYP's project for TEKES (the Finnish Funding Agency for Innovation) funded Mobility as a Service (MaaS) - joint programme. From Tekes programme point of view the goal of this project is to support the realisation of an open innovation platform for mobility services first in the world in Finland - also merging nationwide taxi services via one single API to the platform.

1.3. Abbreviations          

MaaS: Mobility as a Service TYP: Taksiliiton Yrityspalvelut Oy Taksiliitto: The Finnish Taxi Owners Federation TEKES: The Finnish Funding Agency for Innovation API: Application programming interface REST: Representational State Transfer JSON: JavaScript Object Notation HTTP: Hyper Text Transfer Protocol URL: Uniform Resource Locator WGS84: World Geodetic System, 1984

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

4 (10)

[LUONNOS/DRAFT]

22.12.2015

2. Mobility as a Service -operator requirements Mobility as a Service -operators mission is to provide seamless, smooth and easy to use door-to-door mobility services for end-users. However, the Taxi API is not only for full scale MaaS -solutions. It can also be used just for ordering a taxi. In any case, MaaS -operator is required to make an agreement with TYP, before using the Taxi API.

2.1. Contracts There are two types of contracts depending on MaaS -operators targeted service level. These types are ”Basic level of contract” and ”Professional level of contract”.

2.1.1 Basic level of contract for ordering taxis This contract makes possible to implement use cases described in this document (sections 3.1 , 3.2, 3.3 and also 3.4). MaaS -operator is not able to pay taxi journeys, so operators customer must pay for the taxi driver in the end of the journey. To make a basic level of contract, MaaS -operator must be: 

a company or an organization (legal personality)



aware of limitations and terms of use

2.1.2 Professional level of contract for ordering prepaid taxis This contract makes also possible to implement use cases described in this document (sections 3.2 , 3.2, 3.3 and 3.4). MaaS -operator is able to pay taxi journeys (prepaid taxi), so operators customers can use a taxi without paying for the taxi driver in the end of the journey. This means that implementing e.g. prepaid taxi sharing -services are possible and price of the journey can be part of the MaaS -operators and end-users deal (e.g. price can be lower than normally and profit can be divided to customer and MaaS -operator). To make a professional level of contract, MaaS -operator must be: 

a company or an organization (legal personality)



a company or an organization with a good financial standing



aware of limitations and terms of use



aware of agreements needed between MaaS operator and areal taxi organisations to enable payment transactions between MaaS operator and taxis

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

5 (10)

[LUONNOS/DRAFT]

22.12.2015

2.2 Common requirements for MaaS-operator 1. Taxi API does not currently provide any interface to query detailed information about created orders i.e. only current statuses for orders can be queried from the API. This is why MaaS-operator is responsible to manage and save/update successfully created/updated order details in its internal data system (e.g. order id, customer details, trip details). MaaS-operator is also required to continuously poll Taxi API's status-API to stay updated on changes for pending orders. This way MaaS-operator is able to notify customers about orders' status changes and keep in track and up to date with pending orders and their details. In the future Taxi API may provide an asynchronous "Status channel subscription" -implementation to provide MaaS-operator a channel to get notifications about status changes as "push" -events. This would make the status polling obsolete. 2. Taxi API does not currently provide interface to update existing order by id. To update an order, for now it is made by cancelling the order with Cancel-request followed by creating a new order with Order-request. MaaS-operator must rely on its internal data system to keep up to date with the possible changes in the orders and related customer notifications. (Related also to Taxi API constraint 1. in this listing) 3. MaaS-operator is responsible of creating/updating taxi sharing ("kimppakyyti") orders and notifying affected customers about the possible changes in taxi sharing -orders. MaaSoperator must rely on its internal data system to keep up to date with the possible changes in the taxi sharing orders and customer notification. (Related also to Taxi-API constraint 1. in this listing) 4. MaaS -operator is responsible to report a valid end user's phone number, so that a taxi driver can contact to the client in case of no-show or something similar. 5. MaaS operator must be aware of Finnish Taxi's service level, organisation structure, basic usage etc.

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

6 (10)

[LUONNOS/DRAFT]

22.12.2015

3. Use cases 3.1. Basic use case: Ordering a Taxi - Ad-hoc 3.1.1. Overview In this use case, the MaaS-operator is able to order a taxi to clients location by using the Taxi API. First available taxi will receive the order and estimated arrival time will be given to the MaaS -operator.

3.1.2. Needed interfaces (Sequence diagram for ordering a taxi ad-hoc)

[Sequence diagram for ordering a taxi ad-hoc]

3.1.3 Notes  

MaaS-operator is responsible for generating "provider_order_id" per customer per order MaaS-operator is responsible for notifying customer(s) about order status changes, if it is required by customer (such as: "AcceptedByVehicle", "VehicleLocation", etc..)

3.2. Basic use case: Pre ordering a Taxi at specific time 3.2.1. Overview In this use case, the MaaS-operator is able to order a taxi to clients location in advance at specific time by using the Taxi API. Taxi can be ordered max. two weeks and min. 30 minutes before the journey. MaaS-operator is able to do changes typically min. 30 minutes before requested arrival time by cancelling the order and making a new order if needed. Estimated arrival time will be given to the MaaS-operator, when a certain taxi-car receives the order about 5-15 minutes before requested

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

7 (10)

[LUONNOS/DRAFT]

22.12.2015 arrival time. These time limits are subject to change and may vary depending of location (city, countryside etc.) and time of the day.

3.2.2. Needed interfaces (Sequence diagram for pre ordering a taxi)

[Sequence diagram for pre ordering a taxi]

3.2.3 Notes    

MaaS -operator is responsible for generating "provider_order_id" per customer per order When ordering taxi in advance (creating a preorder), the order request needs to have the "at"parameter defined MaaS-operator is responsible for notifying customer(s) about order status changes, if it is required by customer (such as: "AcceptedByVehicle", "VehicleLocation") Order can be cancelled/updated as long as the pending order status is "Received", "PreorderReceived", "ReceivedByDispatch" or "RequestingVehicle" Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

8 (10)

[LUONNOS/DRAFT]

22.12.2015

3.3. Complex use case: Taxi sharing - Ordering a Taxi for a group of people from/to multiple locations 3.3.1. Overview In this use case, the MaaS -operator is able to order a taxi sharing ("kimppakyyti") taxi to multiple clients and from/to multiple locations in advance by using the Taxi API. MaaS -operator has also possibility to query the estimated price (non-binding) for the order before completing it. A journey can be prepaid or paid in a taxi-car. In case of prepaid journey, taxi can be ordered max. two weeks and min. 30 minutes before the journey and MaaS -operator is able to do changes typically 30 minutes before requested arrival time by cancelling the order and making a new order if needed. Estimated arrival time will be given to the MaaS -operator, when a certain taxi-car receives the order about 5-15 minutes before requested arrival time. These time limits are subject to change and may vary depending of location (city, countryside etc.) and time of the day.

3.3.2. Needed interfaces (Sequence diagram for ordering a taxisharing)

[Sequence diagram for ordering a taxisharing]

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

9 (10)

[LUONNOS/DRAFT]

22.12.2015

3.3.3 Notes       

MaaS -operator is responsible for generating "provider_order_id" per customer per order When preordering a taxi, the order request needs to have the "at"-parameter defined MaaS -operator is responsible for notifying customer(s) about order status changes, if it is required by customer (such as: "AcceptedByVehicle", "VehicleLocation") Order can be cancelled/updated as long as the pending order status is "Received", "PreorderReceived", "ReceivedByDispatch" or "RequestingVehicle" Destination information is not always sent to driver of the taxi, so MaaS -operators clients should be aware of destination addresses. MaaS -operator is responsible to plan feasible schedules for the taxisharing journeys. One order means always a one taxi-car. If you need many cars, you have to make many orders.

3.4 Common use cases related to MaaS-operator order management using Taxi API 3.4.1 Current status for orders Maas-operator is responsible for monitoring the status changes of active orders. Currently the only way to keep up to date with the Taxi API order status changes is to poll constantly its "status for orders" -API.

[Sequence diagram: Current status for orders]

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi

Taxi API -service documentation

10 (10)

[LUONNOS/DRAFT]

22.12.2015

3.4.2 Cancel an order Maas-operator may have to update or cancel an existing order. (If order is updated, it needs to be first cancelled and then create a new order with the updated data.)

[Sequence diagram: Cancel an order]

4. Technical interface specification Technical API specification can be found from this link: Will be updated, when the Taxi API service is in production. Technical specification is under development process. Changes will be updated to the website and document history can be found from the beginning of the page. MaaS -operators are obligated to keep track of the changes.

5. Other 5.1 Contact information Will be updated, when the Taxi API service is in production.

5.2 Help and Assistance Will be updated, when the Taxi API service is in production.

Taksiliiton Yrityspalvelu Oy | Nuijamiestentie 7 | 00400 Helsinki | Y-tunnus: 0645272-9 | www.taksiliitto.fi