TaxiAPI Specification for MaaS operators

Transcription

1 TaxiAPI Specification for MaaS operators Version 1.0 Last edited at: :37 by Mikko Harju Definitions The following notation is used when describing the data types used in a response. The standard data type serialization format is determined by the JSON specification. <int> - An integer, e.g <string> - A string, wrapped in quotes e.g. "hello" <bool> - A boolean value e.g. true or false <double> - A double precision floating number <uuid> - A Universal Unque Identifier, a 128 byte value encoded as a hex-string. e.g. "314837dc-0e7f-11e3-bebe-accf18156acf" <timestamp> - An ISO-8601 serialized Date format e.g. " T00:12:00+02:00" <currency> - String-valued, dot-separated currency in Euro. Prefer non-floating point implementations when parsing. e.g. "10.40" <url> - A valid RFC 1738 URL for the linked resource Flags<enum> - A bitwise ORred collection of values from the given enumeration <datatype<*>> - An array consisting of zero or more elements of the given type <datatype<n>> - An array with a fixed number of elements <datatype?> - Optional value, can be omitted completely if empty <dt1> <dt2> - Conditional types, can be one of the alternatives The type description of the response is followed by a concrete example. Should the feed endpoint be a POST, PUT or DELETE, the section contains the request data specification, the response data specification and an example request-response -pair. The fields that can have empty values are omitted from the response message. No null values should be presented from the server to the client. Application identification The MaaS-operator uses the User-Agent HTTP field to identify itself to the server. The information is used to gather statistics and information on the performance on a given application. Use the following identifiers for the clients: TaxiAPI/<Operator> <major.minor.build>. Where Operator is the name assigned to the operator by Taksiliiton Yrityspalvelu. In addition the requests are identified and verified with SSL Client Certificates that are provided for the MaaS operator from Taksiliiton Yrityspalvelu. The certification process goes roughly as follows: 1. The MaaS operator sends a proper CSR to Taksiliiton Yrityspalvelu, with the Taksiliiton Yrityspalvelu assigned common name (CN). 2. Taksiliiton Yrityspalvelu signs a new key with the given CSR and sends it back to the MaaS operator. 3. The MaaS operator uses the key to verify connections to the server. 1

2 Common datatypes and API conventions The localization for the server messages are handled by the Accept-Language HTTP header. Currently supported languaage codes are en, fi and se. The application should send the Accept-Language header on every request. However if it is omitted or it is outside of the known values, en is used as the default. The responses are specified with a HTTP Status code indicating the status of the performed operation. The response specifications show the given HTTP status code in the comment preceding the response definition. The error codes that are possible outcomes from a request are specified in the documentation. These cases must be handled gracefully by the client. If there are places where flaggable enumerations are used, they are marked as Flags (for an example, see TaxiCenter). The field contains bitwise-orred value with the given datatype. The actual value of each flag is defined by the enumeration. Check the actual values and use them, since the grouping might not be by increasing order in value. = <int> <Error> // Possible values specified by the endpoint "code":, // Specified in the language given by the Accept-Language parameter "localized_description": <string> <Capability> // Order capabilities Preorder=1, Prepaid=2, VehicleTypeSelection=(1<<2), // Feature capabilities VehicleLocationReporting=(1<<3), AvailabilityInformation=(1<<4), // Preorder address requirements PreorderDestinationAddressRequired=(1<<5), PreorderDestinationAddressAllowed=(1<<6) // What vehicle types do we support? VehicleTypeCombiSupported=(1<<7) VehicleTypeMinibusSupported=(1<<8) <Settings> "telephone": <string>, <GeoCoordinate> "lat": <double>, "long": <double> // Horizontal accuracy in meters, if applicable "accuracy": <double?> 2

3 <TaxiCenter> "id": <int>, "name": <string>, "order_price" <currency>, "preorder_price" <currency>, "capabilities": Flags<Capability>, "settings": <Settings> <NamedLocation> "distance": <double>, // Coordinate can be used for e.g. normalizing pin location after reverse geocode "coordinate": <GeoCoordinate>, // Use when submitting the order "order_address": <string>, "order_city": <string> // Use when displaying to the user // TITLE as the main large heading "localized_title": <string>, // SUBTITLE as the smaller detail text "localized_subtitle": <string>, // The taxi center whose capabilities should be used "taxi_center": <TaxiCenter> <Contact> "phone_number": <string>, "name": <string?>, "message": <string?>, "provider_order_id": <string?>, // The passenger count in the given order "passenger_count": <int> <Address> "street_address": <string>, "city": <string> <LocationType> "pickup", "destination" <Location> "address": <Address?>, "coordinate": <GeoCoordinate?>, "type": <LocationType>, "contacts": <Contact*>, 3

4 "drop_off": <string*>, "at": <datetime?>, // The passenger count entering or leaving the vehicle at the location "passenger_count": <int> <VehicleTypeAttribute> "combi" "minibus" // Vechile attributes type not yet in use, just an example of what could be there <VehicleAttribute> "ecofriendly","electric","wheelchair","childseat","driverless" <Order> "locations": <Location*>, "submitted": <datetime>, "prepaid": <bool?> "vehicle_type": <VechicleTypeAttribute?> Operational semantics The server will implement the at-least-once delivery gurantees for all incoming messages. It means that if the client should send the same request many times, only one operation will have side-effects and the rest are idempotent. This means that the client may attempt delivering messages until it has received a verification from the server. The verification normally comes as a response for the actual POST or PUT but if it should fail it is OK to send the request again. Just make sure the request body is a completely identical to the previous message and the server will know if it should process the message or not. If the message is not processed we will return HTTP status code 409 Conflict denoting that the request was already processed by the system. List of error codes 100 = UnsupportedLocation 101 = UnknownIdentifier 103 = UnknownLocation 105 = OperatorBlocked 106 = OperatorUnknown 108 = OrderAlreadyReceived 111 = UnsupportedDatetimeForLocation 112 = InvalidPlatform 113 = UnknownOrder 114 = TooLateToCancelOrder 115 = NotAuthorized 116 = UnsupportedDispatchCenter 117 = ServerInPanicMode 118 = ClientVersionNotSupported 119 = LocationWarning 120 = InsufficientAccuracy 200 = MessageErrorVehicleHasNotAccepted 201 = MessageErrorOrderCompleted 4

5 GET 300 = NoPickupLocation 301 = PreorderingNotSupported 302 = DestinationAddressNotAllowed 303 = DestinationAddressRequired 304 = VehicleTypeSelectionNotAllowed 305 = InvalidVehicleType 306 = MissingProviderOrderID 307 = MissingPhoneNumber Taxi center by location GET /center/by-location/?lat=<double>&long=<double>&accuracy=<double> Gets the taxi center that is operating in the given location and must be used when performing taxi center related operations for the user. order_price and preorder_price are decimal number strings with a dot separator and two decimal digits, like "2.00" or "3.55", displaying the price in euros. Response <TaxiCenter> // HTTP 404 Not Found 100=UnsupportedLocation <Error> Example "id": 1, "name": "V-S Taxidata", "order_price": "2.50", "preorder_price": "7.00", "capabilities": 9, "settings": "telephone": " " // HTTP 404 Not Found "code": 100, "localized_description": "Et ole määriteltyjen taksikeskusten alueella." Taxi center by ID GET /center/<id>/ 5

6 Response <TaxiCenter> // HTTP 404 Not Found 101=UnknownIdentifier <Error> Example "id": 1, "name": "V-S Taxidata", "order_price": "2.50", "preorder_price": "7.00", "capabilities": 9, "settings": "telephone": " " // HTTP 404 Not Found "code": 101, "localized_description": "Valittua taksikeskusta ei löydy." Current status for Orders GET /orders/<order-id?> Gets the statuses for pending orders for the current MaaS operator or a single order belonging to it if given as a parameter order_id. The status may contain data relating to it in the data field. For now this is only if the status is VehicleLocation and the handling taxi center supports posting the location (see Common datatypes and API conventions). If no pending orders exist, the value for statuses in the JSON will be an empty array. Response // HTTP 200 <StatusCode> Received = 1 ReceivedByDispatch = 9 Accepted = 12 PreorderReceived = 8 RequestingVehicle = 2 AcceptedByVehicle = 3 VehicleLocation = 4 NoContactWithVehicle = 10 NotOperational = 11 PassengerInVehicle = 14 6

7 Example Complete = 5 Error = 6 Canceled = 7 <Fallback> "telephone": <string> Parameter<Accepted> "dispatch_id": <string> Parameter<AcceptedByVehicle> "vehicle_id": <string>, Parameter<VehicleLocation> "vehicle_id": <string>, "lat": <double>, "long": <double>, // Arrival time is set on the first location information is received i.e. It is not updated cons "estimated_arrival_at": <datetime> <Status> "order_id": <int>, "timestamp": <timestamp>, "code": <StatusCode>, "localized_description": <string>, // Type is dependent on the actual value of code "data": Parameter<code> "fallback": <Fallback?> "statuses": <Status*> "statuses": [ "order_id": 58, "timestamp": " T08:19:00+03:00", "code": 3, "localized_description": "Taksikeskus on vastaanottanut tilauksen.", "data": "dispatch_id": , 7

8 ] "order_id": 59, "timestamp": " T08:19:00+03:00", "code": 3, "localized_description": "Auto 1234 hyväksyi tilauksen ja on matkalla.", "data": "vehicle_id": 1234, "order_id": 60, "timestamp": " T08:19:00+03:00", "code": 4, "localized_description": "Taksi on matkalla!", "data": "lat": , "long": Reverse geocoding by coordinate GET /address/by-coordinate/?lat=<double>&long=<double>&accuracy=<double> Gets the reverse geocoded address for the given coordinate. We will use the Accept-Language HTTP header field to show the address in the desired language. The orders will be passed by to the Taxi centers in Finnish. If the address is correctly reverse geocoded but no corresponding taxi centers exist, an UnsupportedLocation error will be returned. If the taxi center for the address exists but does not support ordering, an UnsupportedDispatchCenter error will be returned. Response // HTTP 200 <NamedLocation> // HTTP =UnsupportedLocation, 116=UnsupportedDispatchCenter // HTTP =UnknownLocation, 120=InsufficientAccuracy <Error> Example "distance": 25.0, "coordinate": "lat": 60.2, 8

9 "long": 22.2, "localized_title": "Yliopiston Apteekki", "localized_subtitle": "Universitetsgatan 25, Åbo", "order_address": "Yliopistonkatu 25", "order_city": "Turku", "taxi_center": "id": 1, "name": "V-S Taxidata", "order_price": "2.50", "preorder_price": "7.00", "capabilities": 9, "settings": "telephone": " " // HTTP 403 Forbidden "code": 100, "localized_description": "Tälle osoitteelle ei löydetty taksikeskusta." "location": "distance": 25.0, "coordinate": "lat": 60.2, "long": 22.2, "localized_title": "Yliopiston Apteekki", "localized_subtitle": "Universitetsgatan 25, Åbo", "order_address": "Yliopistonkatu 25", "order_city": "Turku" // or "code": 116, "localized_description": "Taksin tilaaminen tähän osoitteeseen sovelluksen kautta ei ole vielä m "location": "distance": 25.0, "coordinate": "lat": 60.2, "long": 22.2, "localized_title": "Yliopiston Apteekki", "localized_subtitle": "Universitetsgatan 25, Åbo", "order_address": "Yliopistonkatu 25", "order_city": "Turku", "taxi_center": "id": 1, "name": "V-S Taxidata", "order_price": "2.50", "preorder_price": "7.00", "capabilities": 9, "settings": "telephone": " " 9

10 // HTTP 404 Not Found "code": 103, "localized_description": "Et voi tilata taksia annettuun osoitteeseen. Syötä uusi osoite." // or "code": 120, "localized_description": "Sijaintia ei voitu määrittää riittävän tarkasti." Order locations GET /locations/?city=<string> OR GET /locations/?lat=<double>&long=<double>&accuracy=<double?> OR GET /locations/?term=<string>&city=<string?>&lat=<double?>&long=<double?>&accuracy=<double?> Gets a list of suggestions to be shown to the end user given when creating a new order. The list will be sorted by the server to the order it will be shown to the end user. The search can be performed either with a search term (such as "Lentokenttä"), with a specific location or without either of them. The accuracy parameter specifies the accuracy of the GPS measurement if the coordinate comes from the user s current location. If the location is manually selected from a map instead, then the parameter must be omitted. If the term search is used, please submit only queries with more than 3 characters in length. The lat, long and accuracy-parameters should be submitted along with the term search. This enables sorting the results by user s current location. To limit any of the searches to a given city, provide the parameter city to the query. AddressForCity as a value for type denotes that the application should not take the address as an order address but rather as a suggestion for autocompletion. After the user selects an item of this type, the application should start using the city field along with the term to search the addresses available for that given address-city pair. The result object may contain error if the suggestions are performed with only the coordinate and the location does not offer a decent suggestion. Response <NamedLocationType> SuggestedNearby=2, AddressForCity=3 <LocationList> "suggestion": <NamedLocation>, "type": <NamedLocationType>, "localized_type": <string> 10

11 Example "suggestions": <LocationList*> "error": <Error?> // Same errors as reverse geocoding, and also LocationWarning "suggestions": [ "suggestion": "distance": 25.0, "coordinate": "lat": 60.52, "long": 22.27, "order_address": "Lentoasemantie 150", "order_city": "Turku", "localized_title": "Lentoasemantie 150", "localized_subtitle": "Turku", "taxi_center": "id": 1, "name": "V-S Taxidata", "order_price": "2.50", "preorder_price": "7.00", "capabilities": 9, "settings": "telephone": " ", "type": 2, "localized_type": "Ehdotukset" ], "error": "code": 119, "localized_description": "Ehdotettu paikka on melko kaukana nykyisestä tunnistetusta sijainn // Example for type 3 (AddressForCity) "suggestions": [ "suggestion": "distance": 25.0, "coordinate": "lat": 60.52, "long": 22.27, "localized_title": "Yliopistonkatu", "localized_subtitle": "Turku", "type": 3, "localized_type": "Ehdotukset", "suggestion": "distance": 25.0, 11

12 ] "coordinate": "lat": 60.52, "long": 22.27, "localized_title": "Yliopistonkatu", "localized_subtitle": "Helsinki", "type": 3, "localized_type": "Ehdotukset", "suggestion": "distance": 25.0, "coordinate": "lat": 60.52, "long": 22.27, "localized_title": "Yliopistonkatu", "localized_subtitle": "Tampere", "type": 3, "localized_type": "Ehdotukset" Status channel subscription GET /status/<uuid>/ Subscribe to status messages using a WebSocket connection. The UUID of the device whose status is to be listened to is given as parameter. The posted messages and their format currently match the Current status for orders endpoint, but this is subject to change. POST Validate location and datetime before ordering POST /order/validate/ Validates an Order. This allows you to give the user feedback about a possibly invalid departure address or (pre)order datetime before order creation is attempted. If the address and (preorder or current) datetime are valid, an empty HTTP 200 OK response is returned. If one of them is invalid, an HTTP 403 Forbidden response is returned with a corresponding error code. The UnsupportedLocation error code will be returned if a taxi cannot be ordered to Location, regardless of whether a preorder datetime is specified or not. The UnknownLocation error code will be returned if the address given in Location does not exist. The UnsupportedDatetimeForLocation error code will be returned if the Location itself would be allowed, but is temporally restricted at the current time or at the time specified by the at parameter. The localized_description field will vary depending on whether at was given or generated by server i.e. if we re dealing with a preorder or with a regular order. The UnsupportedDispatchCenter error code will be returned if the taxi center matching the Location does not yet support ordering via API this enables the client to e.g. show the taxi center phone number. Request <Order> Response with empty body // HTTP 403 Forbidden 12

13 100=UnsupportedLocation 111=UnsupportedDatetimeForLocation 116=UnsupportedDispatchCenter // HTTP 404 Not Found 103=UnknownLocation, <Error> Example // POST /order/validate/ "locations": [ "address": "street_address": "Ratapihankatu 30",, "type": "pickup", "at": " T09:48:23+03:00", "passenger_count": 4, "contacts": [ "phone_number": " ", "name": "Mikko Harju", "provider_order_id": "MaaS-67859", "passenger_count": 3, "phone_number": " ", "name": "Minna Möttönen", "provider_order_id": "MaaS-67860", "message": "Tarvitsen apua laukun kantamisessa!", "passenger_count": 1 ], "address": "street_address": "Arvinkatu 19",, "type": "destination", "drop_off": ["MaaS-67860"], "passenger_count": 1, "address": "street_address": "Itäinen pitkäkatu 25", 13

14 ,, "type": "destination", "drop_off": ["MaaS-67859"] "passenger_count": 2 "address": "street_address": "Itäinen pitkäkatu 1",, "type": "destination", "drop_off": ["MaaS-67859"] "passenger_count": 1 ], "submitted": " T22:32:10+03:00", "prepaid": true // HTTP 403 Forbidden "code": 100, "localized_description": "Et ole määriteltyjen taksikeskusten alueella." // or "code": 111, // preorder error text "localized_description": "Valitsemaasi osoitteeseen ei voi ennakkotilata taksia antamanasi ajank // or "code": 111, // regular order error text "localized_description": "Valitsemaasi osoitteeseen ei voi tilata taksia juuri nyt." // or "code": 116, "localized_description": "Taksin tilaaminen tähän osoitteeseen sovelluksen kautta ei ole vielä m // HTTP 404 Not Found "code": 103, "localized_description": "Et voi tilata taksia annettuun osoitteeseen. Syötä uusi osoite." Request for a new taxi to location POST /order/ Requests a taxi to take in passengers from nodes with type pickup. Additionally the order can specify destination nodes to denote the destinations. The changes in the order s status will be reflected in the Current status for orders and Status channel subscription endpoints. If the at parameter is defined, the order is a preorder. 14

15 If the prepaid flag is set, the order has been paid in advance and the users will not pay for the trip in the vehicle. This is available only for professional contracts. If the vehicle_type field is set in the order, the order can be fullfilled also with a vehicle with more seats than the order states. For example, for an "any" taxi (also the default if the parameter is not specified), the order can be fullfilled with a "any" a "combi" or a "minibus". For orders with "combi" can be fullfilled with "combi" or "minibus". The end user must know that for specific kind of requests the fullfillment can take a long time. If the capabilities field of a TaxiCenter specifies the PreorderDestinationAddressRequired flag, destination is required. If capabilities specifies the PreorderDestinationAddressAllowed flag, destination is optional. If both flags are set, PreorderDestinationAddressRequired takes presedence and destination is required. If the vehicle_type field is set in the order, the Operator must take care that the order is fulfillable with the request. For example, if there are 10 passengers in the order and a combi (Station Wagon) vehicle is requested, the route must contain at most 4 passengers between successive pickup and drop_off nodes. The submitted parameter must be generated by the client once per order. If, for some reason (e.g. bad network connectivity) the client needs to re-send the order, the submitted parameter MUST be the same as it was in previous attempts. This is the only way to distinguish between order requests that are automatically re-sent by the client application (identical submitted values) and multiple user-originated orders (different submitted values), when the user wants to order (or preorder with the same at time) multiple taxis to the same location. The phone number of the users participating in the ride can be sent in the contacts field so that the driver can contact the users should there be a need for it. If the backend has already received an order with a given submitted timestamp, it will respond with a HTTP 200 OK status code. Request <Order> Response // HTTP 202 Accepted <OrderResponse> "id": <int> <OrderResponse> // HTTP 400 Bad Request <ValidationError> "field": <string>, "localized_error": <string> "errors": <ValidationError*> // HTTP 403 Forbidden 120=InsufficientAccuracy 15

16 // HTTP 403 Forbidden 105=OperatorBlocked // The address (and perhaps datetime) have been submitted despite the fact // that one or the other would have failed validation; see "Validate location // and datetime before ordering" for details. 100=UnsupportedLocation 111=UnsupportedDatetimeForLocation 116=UnsupportedDispatchCenter // HTTP 404 Not Found 103=UnknownLocation, // HTTP 409 Conflict 108=OrderAlreadyReceived <Error> Example // POST /order/ "locations": [ "address": "street_address": "Ratapihankatu 30",, "type": "pickup", "at": " T09:48:23+03:00", "passenger_count": 4, "contacts": [ "phone_number": " ", "name": "Mikko Harju", "provider_order_id": "MaaS-67859", "passenger_count": 3, "phone_number": " ", "name": "Minna Möttönen", "provider_order_id": "MaaS-67860", "message": "Tarvitsen apua laukun kantamisessa!", "passenger_count": 1 ], 16

17 ,,, "address": "street_address": "Korpijärventie 2",, "type": "pickup", "contacts": [ "phone_number": " ", "name": "Make Kotilainen", "provider_order_id": "MaaS-67861", "passenger_count": 1 ], "passenger_count": 1 "address": "street_address": "Arvinkatu 19",, "type": "destination", "drop_off": ["MaaS-67860"], "passenger_count": 1 "address": "street_address": "Itäinen pitkäkatu 25",, "type": "destination", "drop_off": ["MaaS-67859"] "passenger_count": 2 "address": "street_address": "Itäinen pitkäkatu 1",, "type": "destination", "drop_off": ["MaaS-67859", "Maas-67861"] "passenger_count": 2 ], "submitted": " T22:32:10+03:00", "prepaid": true, "vehicle_type": "minibus" // HTTP 202 Accepted "id": 1234 // HTTP 400 Bad Request "errors": [ 17

18 ] "field": "at", "localized_error": "Et voi tilata taksia annetulle päivälle." // HTTP 403 Forbidden "code": 105, "localized_description": "Tämä operaattori on tilauskiellossa." // HTTP 409 Conflict "code": 108 "localized_description": "Tilaus on jo vastaanotettu." Price estimate for order POST /order/pricing/ Provides a non-binding estimate for the order given as parameter. The data should be the same that is submitted to the Request for a new taxi to location endpoint. The response contains the price for the total journey specified by the order. Request <Order> Response Example "price": <currency> // POST /order/pricing/ "locations": [ "address": "street_address": "Ratapihankatu 30",, "type": "pickup", "at": " T09:48:23+03:00", "passenger_count": 4, "contacts": [ "phone_number": " ", "name": "Mikko Harju", "provider_order_id": "MaaS-67859", "passenger_count": 3, "phone_number": " ", 18

19 ,, ] "name": "Minna Möttönen", "provider_order_id": "MaaS-67860", "message": "Tarvitsen apua laukun kantamisessa!", "passenger_count": 1 "address": "street_address": "Arvinkatu 19",, "type": "destination", "drop_off": ["MaaS-67860"], "passenger_count": 1 "address": "street_address": "Itäinen pitkäkatu 25",, "type": "destination", "drop_off": ["MaaS-67859"], "passenger_count": 3 ], "submitted": " T22:32:10+03:00", "prepaid": true "price": "16.70", Send a message to the driver POST /order/<order-id>/send-message/ NOT YET IMPLEMENTED IN THE FIRST RELEASE Sends a message through the dispatch center to the vehicle that has accepted the order. The order must be in a state there is a possibility to send a message to the driver, i.e. a vehicle has accepted the order and the order is not yet completed. Request "phone_number": <string>, "message": <string> Response with empty body // or // HTTP 404 Not Found with empty body 19

20 // or Example PUT // HTTP 400 Bad Request <Error> POST /order/12345/send-message/ "phone_number": " ", "message": "Matkalaukkuni on vielä tulossa koneesta. Tulen aivan kohta!" // HTTP 404 Not found // HTTP 400 "code": 200 "localized_description": "Auto ei ole vielä hyväksynyt tilausta." Update a preorder To update a preorder, for now it is made by canceling the order with Cancel an order followed by creating a new preorder with Request for a new taxi to location. DELETE Cancel an order DELETE /order/<order_id>/cancel/ Cancels an order or a preorder. An order can be cancelled as long as a taxi vehicle hasn t yet accepted the order (i.e. as long as Current status for orders returns one of: Received, PreorderReceived, ReceivedByDispatch or RequestingVehicle). If it s too late to cancel an order, HTTP 403 Forbidden will be returned. Response with empty body // HTTP 404 Not Found 113=UnknownOrder // HTTP 403 Forbidden 114=TooLateToCancelOrder 115=NotAuthorized // Order not created by the currently identified MaaS operator 20

21 <Error> Example // DELETE /order/1234/cancel/ // HTTP 404 Not Found "code": 102, "localized_description": "Tilausta 1234 ei ole olemassa" // HTTP 403 Forbidden "code": 114, "localized_description": "Tilausta ei voi enää peruuttaa." // or "code": 115, "localized_description": "Sinulla ei ole oikeutta perua tätä tilausta." 21