Zone Behavior

info

The MaaS API will enforce any zone behavior, meaning that no logic should be created on the consumer side in order to enforce it. The consumer can rely on the relevant RPC's responses and errors.

Currently, consuming Dott's GBFS API is the only way to get information about Geofencing zones and Parking spots. This information might be useful for giving visual representation of the zones to the end user in order to promote an adequate usage or Dott's service as well as to provide a good user experience.

Information about how to interpret GBFS's Geofencing information can be found in the following guides:

• GBFS's Zone Behavior.
• GBFS's Supported Zones.

In which rider zones can't rides be started?

Rides can't be started in the zone where the ride_allowed rule is not set to true.

What should be the API response?

Errors

Status Code	Description	Error Code	Error Detail
400	Bad Request	ERR_BACK_END_CONFIG_NOT_FOUND	google.rpc.PreconditionFailure
409	Conflict	ERR_CONCURRENT_REQUEST	google.rpc.ErrorInfo
400	Bad Request	ERR_DECLINED	google.rpc.PreconditionFailure
400	Bad Request	ERR_ID_VERIFICATION_REQUIRED	google.rpc.PreconditionFailure
500	Bad Request	ERR_INTERNAL	google.rpc.DebugInfo
400	Bad Request	ERR_MISSING_REQUIRED_ACTOR_ID	google.rpc.PreconditionFailure
400	Bad Request	ERR_MISSING_REQUIRED_RIDER_DATA	google.rpc.PreconditionFailure
500	Internal	ERR_REGION_NOT_FOUND	google.rpc.DebugInfo
404	Not Found	ERR_USER_NOT_FOUND	google.rpc.ResourceInfo
404	Not Found	ERR_VEHICLE_DETAILS_NOT_FOUND	google.rpc.ResourceInfo
404	Not Found	ERR_VEHICLE_NOT_FOUND	google.rpc.ResourceInfo
400	Bad Request	ERR_VEHICLE_OFFLINE	google.rpc.PreconditionFailure
400	Bad Request	ERR_VEHICLE_UNAVAILABLE	google.rpc.PreconditionFailure
500	Internal	Unknown	google.rpc.DebugInfo

In which rider zones can't rides be ended?

Rides can only be ended in different zones depending on the Region configuration.

Whenever there is designated parking (meaning that the main Region zone has the station_parking rule set to true), rides can only be ended in a Parking spot with available capacity (this can be obtained via the /station_information.json endpoint).

When there is no designated parking, any zone where both the ride_allowed and ride_allowed rules are set to false prevents the ending a ride.

Additionally, whenever there is a parking photo requirement the API will prevent trips from ending unless a valid skip reason is supplied (by setting the parkingPhotoSkipReason to a valid value in the request body of the EndTrip RPC)., or if it is promised to be uploaded after ending the trip (by setting the promiseParkingPhoto to true in the request body of the EndTrip RPC).

What should be the API response?

Valid Responses where trip did not end

The End Trip RPC response holds a success property. Whenever this is set to false it means the trip did not end. Consumers can find an explanation on why the trip was unable to end in the details property (it is empty when the trip successfully ends), based on this behavior should be derived for the trip to be able to end.

The possible details are:

• EndRideOutsideGeofenceDetails
• EndRidePhotoRequiredDetails

EndRideOutsideGeofenceDetails

Description

Returned when the user attempts to end their ride outside the geofence. This will be returned either until the relocation fee is accepted or the next attempt is not outside the geofence.

Example

{
  "name": "trips/trip-id",
  "success": false,
  "trip": {
    "name": "trips/trip-id",
    "startTimestamp": {
      "seconds": 1234
    },
    "state": 1,
    "userId": "user-id",
    "vehicleType": 2
  },
  "endRideOutsideGeofenceDetails": {
    "relocationFee": {
      "amount": 1000,
      "currency": "EUR",
      "unit": 1
    }
  }
}

EndRidePhotoRequiredDetails

Description

Returned when the user attempts to end their ride in a restricted parking area. This will if a parking photo should be provided via the trips/*/parking_photo relevant endpoint.

If it is impossible to provide a parking photo this can be skipped by passing a PhotoSkipReason.

Example

{
  "name": "trips/trip-id",
  "success": false,
  "trip": {
    "name": "trips/trip-id",
    "startTimestamp": {
      "seconds": 1234
    },
    "state": 1,
    "userId": "user-id",
    "vehicleType": 2
  },
  "endRidePhotoRequiredDetails": {
    "relocationFee": {
      "amount": 1000,
      "currency": "EUR",
      "unit": 1
    }
  }
}

Errors

Status Code	Description	Error Code	Error Detail
400	Bad Request	ERR_MANUAL_LOCK_NOT_LOCKED	google.rpc.PreconditionFailure
400	Bad Request	ERR_PARKING_FORBIDDEN	google.rpc.PreconditionFailure
404	Not Found	ERR_TRIP_NOT_FOUND	google.rpc.ResourceInfo