api.proto

syntax = "proto3";

package coop.drivers.dispatch.v1beta1;

import "coop/drivers/dispatch/v1beta1/driver.proto";
import "coop/drivers/dispatch/v1beta1/latlng.proto";
import "coop/drivers/dispatch/v1beta1/trip.proto";
import "google/protobuf/duration.proto";
import "validate/validate.proto";

service DispatchService {
  // Bulk-ingest driver locations.
  rpc UpdateDriverLocations(UpdateDriverLocationsRequest) returns (UpdateDriverLocationsResponse) {}

  // Bulk-ingest (on-demand or scheduled) trips.
  rpc CreateTrips(CreateTripsRequest) returns (CreateTripsResponse) {}

  // Gets the nearest drivers to a given trip pickup location.
  rpc GetNearestDrivers(GetNearestDriversRequest) returns (GetNearestDriversResponse) {}

  // Gets the nearest trips to a given driver's location.
  rpc GetNearestTrips(GetNearestTripsRequest) returns (GetNearestTripsResponse) {}

  // Lists drivers.
  rpc ListDrivers(ListDriversRequest) returns (ListDriversResponse) {}
}

message UpdateDriverLocationsRequest {
  repeated DriverLocation locations = 1 [(validate.rules).repeated = {
    min_items: 1,
    max_items: 1000
  }];
}

message UpdateDriverLocationsResponse {}

message CreateTripsRequest {
  repeated Trip trips = 1 [(validate.rules).repeated = {
    min_items: 1,
    max_items: 1000
  }];
}

message CreateTripsResponse {}

message GetNearestDriversRequest {
  // trip pickup location
  LatLng pickup_location = 1;
  int32 limit = 2 [(validate.rules).int32 = {
    gt: 0,
    lte: 1000
  }];
}

message GetNearestDriversResponse {
  repeated SearchResult results = 1;
  string pickup_address = 2;
}

message GetNearestTripsRequest {
  oneof driver {
    option (validate.required) = true;

    string driver_id = 1;
    LatLng driver_location = 2;
  }
  int32 limit = 3 [(validate.rules).int32 = {
    gt: 0,
    lte: 1000
  }];
}

message GetNearestTripsResponse {
  repeated SearchResult results = 1;
}

message SearchResult {
  oneof payload {
    Trip trip = 1;
    DriverLocation driver = 2;
  }
  // Driver's distance from the pickup location (in meters)
  double distance_meters = 3;
  // Time it takes driver to go to pickup
  google.protobuf.Duration duration = 4;
  // The match's location.
  LatLng location = 5;
  // Human-readable location
  string address = 6;
  // The highest (finest) H3 resolution in which the match was found.
  int32 resolution = 7;
  // The k-value of the lowest k-ring (most immediate neighborhood) in which the
  // match was found.
  int32 k_value = 8;
  double score = 9;
}

message ListDriversRequest {
  int32 page_size = 1 [(validate.rules).int32 = {
    gt: 0,
    lte: 1000
  }];
  string page_token = 2;
}

message ListDriversResponse {
  repeated DriverLocation driver_locations = 1;
  string next_page_token = 2;
}