Operation Schema

Model

Operation

Operation = PlanOptimizationOperation

The operation model.

Every operation model has an unique identifier, a type field and a done field.

Currently, the only supported operation type is plan_optimization.

---

PlanOptimizationOperation

PlanOptimizationOperation = object

A plan optimization operation.

This operation represents the asynchronous optimization of a plan. It can be cancelled before it is done.

Example

{
  "id": "operations/zeOCJaJCzZhpKVCVAC9o",
  "done": true,
  "type": "plan_optimization",
  "result": {
    "skippedStops": [
      {
        "id": "stop/123",
        "reason": "impossible_time_window"
      }
    ],
    "numOptimizedStops": 20
  },
  "metadata": {
    "startedAt": 1631100800,
    "finishedAt": 1631101600,
    "canceled": false,
    "targetPlanId": "plan/abc",
    "startedBy": "api"
  }
}

Properties

Property	Type	Description
id	OperationId	This is the operation's unique identifier in the API, this can be used directly in the URL to operate on this operation.
done	boolean	This indicates whether the operation is finished or not. Use this field to know when the operation is finished and the results are available.
type	"plan_optimization"	This is the operation's type, it indicates what kind of operation it is.
result	PlanOptimizationOperationResult | OperationError | null	This is the operation's result, it is only present if the operation is finished.
metadata	PlanOptimizationOperationMetadata	The operation's metadata.

Identifier

OperationId

OperationId = `operations/${string}`

An operation id is a string that is unique to an operation. It is used to identify an operation in the API.

Example

"operations/zeOCJaJCzZhpKVCVAC9o"

Fields

OperationError

OperationError = object

An operation error result.

If the operation fails, this is the result model.

Example

{
  "code": "ERR001",
  "message": "Operation failed due to invalid inputs."
}

Properties

Property	Type	Description
code	string	A code that identifies the error.
message	string	A human-readable message that describes the error. This message is not intended to be parsed by machines.

---

PlanOptimizationOperationResult

PlanOptimizationOperationResult = object

The plan optimization operation's result model.

Example

{
  "skippedStops": [
    {
      "id": "plans/zeOCJaJCzZhpKVCVAC9o/stops/rpX5zK2kRFlIfwREp1js",
      "reason": "impossible_time_window"
    },
    {
      "id": "plans/zeOCJaJCzZhpKVCVAC9o/stops/2pX5zK2kRFlIfwREp1js",
      "reason": "impossible_navigation"
    }
  ],
  "numOptimizedStops": 20
}

Properties

Property	Type	Description
skippedStops	PlanOptimizationSkippedStop[]	All of the skipped stops during the optimization, if any.
numOptimizedStops	number	The number of optimized stops considered for optimization for the operation.

---

PlanOptimizationSkippedStop

PlanOptimizationSkippedStop = object

The representation of the skipped stops in the plan optimization operation's result.

Example

{
  "id": "plans/zeOCJaJCzZhpKVCVAC9o/stops/2pX5zK2kRFlIfwREp1js",
  "reason": "impossible_time_window"
}

Properties

Property	Type	Description
id	StopId	This is the stop's unique identifier in the API.
reason	"impossible_time_window" | "impossible_navigation" | "impossible_number_of_stops" | "impossible_order_of_stops" | string	This is the reason why the stop was skipped. impossible_time_window: The stop's time window is impossible to satisfy. impossible_navigation: The stop is impossible to reach. impossible_number_of_stops: The number of stops is impossible to satisfy. impossible_order_of_stops: The order of stops is impossible to satisfy. New reasons may be added in the future.

---

PlanOptimizationOperationMetadata

PlanOptimizationOperationMetadata = object

Metadata about the plan optimization operation.

Example

{
  "startedAt": 1631100800,
  "finishedAt": 1631101600,
  "canceled": false,
  "targetPlanId": "plans/zeOCJaJCzZhpKVCVAC9o",
  "startedBy": "api"
}

Properties

Property	Type	Description
startedAt	number	Timestamp in seconds of when the operation was started.
finishedAt	number | null	Timestamp in seconds of when the operation was finished, if it is finished.
canceled	boolean	Whether the operation was cancelled or not.
targetPlanId	PlanId	The target plan's unique identifier in the API.
startedBy	"api" | "dispatcher" | string	Who started the operation. api: The operation was started by an API call. dispatcher: The operation was started by a dispatcher. New values may be added in the future.