Assigning a Ride to a Vehicle

Once it has been evaluated that a potential Ride is feasible for a Vehicle, there are a few steps to go through to assign a Ride to a Vehicle:

• Check Vehicle’s state and Mission to confirm nothing has changed since evaluating the Ride

• Update the Mission of the Vehicle to include pick-up and drop-off actions for the Ride

Get Vehicle State and Mission

To be able to update the Mission of a specific Vehicle, we need to make sure the Vehicle status has not changed in the meantime, and it is still ready for new Rides. We also need to get the current Mission ID. This information can be retrieved via the GetVehicle endpoint. A Mission update is only possible with the latest Mission ID.

grpcurl -H "authorization: Bearer $ACCESS_TOKEN" -import-path . -proto fleet_state.proto -emit-defaults \
-d "{ \"vehicle_id\": \"$VEHICLE_ID\" }" \
fleet-api.int.eu-central-1.moia-group.io:443 moia.fleet.state.v1beta4.FleetStateService/GetVehicle

Update Vehicle’s Mission

With the Mission ID from the previous step, we now update the Waypoints of the current Mission via the UpdateVehicleMission endpoint to include all Waypoints and actions for this Ride. With this endpoint, we can either:

• Add Waypoints to existing Mission: e.g. the Vehicle is instructed to go to a new location to perform a pick-up action at the new Waypoint.

• Edit Waypoints of existing Mission: e.g. the Vehicle was already instructed to go to a Waypoint location for a pick-up or drop-off, and we add another pick-up action to the corresponding Waypoint

• Remove Waypoints of existing Mission: e.g. the Vehicle was instructed to go to a Waypoint to perform a rebalancing action but because of the new Ride, this Waypoint is no longer needed and has been removed

The request message for UpdateVehicleMission contains:

• previous_mission_id is the current and latest Mission ID, retrieved in the previous step. This is used to ensure that the Mission is only updated if the previous Mission is still the current Mission.

• vehicle_id is the ID of the Vehicle intended to carry out the Ride.

• waypoints is the array of Waypoints that we want the updated Mission to consist of.

Here is a grpcurl exemplary request message to add Waypoints for a Pick-up and a Drop-off Action for a Ride. In this case, the Vehicle has no other Waypoints or Waypoint Actions in its Mission which should be executed before or after the Ride.

{
  "previous_mission_id": "639332eb-5873-32c8-9c2f-100d73c4c067",
  "vehicle_id": "095f8f65-afd7-4271-bc8a-0e9a516c8c45",
  "waypoints": [
    {
      "location": {
        "location": {
          "latitude": 30.330977,
          "longitude": -97.737064
        },
        "heading": 55,
        "labels": {
          "en": ""
        }
      },
      "actions": [
        {
          "pickup": {
            "ride_id": "66984ed5-bf26-4613-b5b6-7532df536912",
            "promised_arrival_time": {
              "start_time": "2024-07-15T15:18:05Z",
              "end_time": "2024-07-15T17:18:05Z"
            }
          }
        }
      ]
    },
    {
      "location": {
        "location": {
          "latitude": 30.252193,
          "longitude": -97.746808
        },
        "heading": 55,
        "labels": {
          "en": ""
        }
      },
      "actions": [
        {
          "dropoff": {
            "ride_id": "66984ed5-bf26-4613-b5b6-7532df536912",
            "promised_arrival_time": {
              "start_time": "2024-07-15T18:18:05Z",
              "end_time": "2024-07-15T19:18:05Z"
            }
          }
        }
      ]
    }
  ]
}

Note

If you use another client to evaluate the API, you may need to switch the time format to:

“start_time”: { “seconds”: “1709893903”, “nanos”: 613000000 }

grpcurl -H "authorization: Bearer $ACCESS_TOKEN" -import-path . -proto fleet_state.proto  --emit-defaults \
-d "$REQUEST_MESSAGE" \
fleet-api.int.eu-central-1.moia-group.io:443 moia.fleet.state.v1beta4.FleetStateService/UpdateVehicleMission

Mission Update is acknowledged when successful. It returns the new Vehicle Mission with a new Mission ID. If the call fails, it returns a rich error with details on why it failed. Possible reasons for that can be:

• A bad request message. We should correct the request message and retry the call.

• An outdated Mission ID, if the previous_mission_id value in the request was not correct. We need to check the Mission ID and repeat the steps.

• Deadline exceeded if the Mission took too long to update. Retry executing with the same request message.