Trip Plans

Taxi & Private Hire › Products › Trip › Trip Plans

Generally available

A unit of work is one self-contained run of driver work — typically an uninterrupted sequence of stops. A simple trip produces one per segment; multi-load and merged trips produce composite units spanning several segments. Each carries its ordered stops, route and own lifecycle; the driver app navigates by these units and the operator console shows them as the planned execution.

One trip, one or more units of work

A trip is the booking — who travels, from where, to where. A unit of work is what the driver actually carries out: one self-contained run of stops, done in order, with no interruption. A simple A→B trip is a single unit of work. A shared ride, a school run, or trips the system merges together become several units — each one a place to be, with the stops that happen there.

Each unit of work is a place to be, with the stops that happen there, in the order the driver should do them. Two passengers arriving at the same school collapse into one stop.

The driver only ever sees the next run

However tangled the booking is underneath — several passengers, several segments, time windows — the driver app shows one simple thing: go here, do these stops, then on to the next. The system has already worked out the order; the driver just follows it. That is the whole point of a unit of work — it turns a complex plan into a straight line of work.

The driver app never asks the driver to untangle the booking — it just lists the next stop. Capacity, time windows and pickup-before-dropoff are all guaranteed by the order the system chose.

How a unit of work runs

The driver app pulls the current unit of work, and the driver marks each stop as they reach it — arrived, then finished (or no-show). When the last stop of a unit is done, the trip automatically advances to the next unit, until the run is complete. Each unit also carries its own approach route and an estimated arrival time, calculated from real driving distances.

How that order is actually computed — the working order, vehicle size and route — is covered in Trip Planning System.

Example request

GET /client/{clientId}/trip/{tripId}/work ▷ Try it

See the API reference for the full request and response schema.

Endpoints

Method	Path
GET	/client/{clientId}/trip/{tripId}/work · primary	▷ Try it
POST	/client/{clientId}/trip/{tripId}/work	▷ Try it

Full request/response schemas and an interactive explorer will live in the API reference (coming soon).

Related

• Trips
• Trip Segments
• Trip Stops

Fields

Field	Type	Description
trip	Trip	Parent Trip. A trip's segments produce one or more units of work that the driver executes in `sequence` order.
startLatitude	decimal	Origin latitude (WGS-84). For the first UoW this is the driver's GPS at dispatch; for later UoWs this is the previous UoW's end coordinate.
startLongitude	decimal	Origin longitude (WGS-84). See startLatitude for semantics.
endLatitude	decimal	Destination latitude — the pickup-coordinates of the first stop in this UoW.
endLongitude	decimal	Destination longitude. See endLatitude.
tripSegmentStops	Collection	Stops the driver processes at this location — pickup, dropoff, or waypoint. Driver app prompts at each in order.
sequence	smallint	0-indexed execution order within the parent Trip. The driver app walks UoWs in ascending sequence; UoW N starts where UoW N-1 ended.
route	Route	Approach route from start to end coordinates — distance, duration, encoded polyline geometry. Computed by the system against the routing service.
dwellSeconds	integer	Time allocated at this location for stop processing (seconds). Computed as stopCount × 120s — folded into ETA accumulation for downstream UoWs.
estimatedArrivalDate	integer	Projected arrival unix timestamp at the end coordinate. Accumulates from the previous UoW's end time + route duration + dwell.
startDate	integer	Actual execution-start unix timestamp — set by the lifecycle when the UoW transitions to INPROGRESS. Compare against estimatedArrivalDate for ETA accuracy.
status	TripUnitOfWorkLifecycleEnum · NONE | INPROGRESS | FINISHED | CANCELLED	Lifecycle state: NONE (pending) → INPROGRESS (driver started) → FINISHED (all stops done) | CANCELLED (operator override). Drives both driver-app navigation and operator dashboards.
clientId	bigint	Tenant scope. Every tenant-aware entity carries this; `ClientFilter` enforces row-level isolation on read; the multi-tenancy routing layer (`/client/{clientId}`) sets it at create time. Surfaced only under `admin` / `tripLog` groups — never to end users.
internalKey	string	Optional client-supplied external reference / idempotency key. When present, lets external systems correlate platform-side records back to their own source-of-truth ids. Not persisted to a column — populated by the request handler when the caller sets it.
__objectType	string	Discriminator string (entity class short-name) emitted alongside the id in serialized output. Resolved at read time by `getObjectType()`; lets the FE dispatch entity-specific rendering without inspecting the URL.
id	bigint	Snowflake-style primary key (unsigned BIGINT). Generated by `IdFactory` at create time; surfaced to the FE / API as a `G`-prefixed string and stripped back to plain bigint server-side before Doctrine lookup.
createdDate	integer	Unix timestamp the row was first persisted. Set in the entity's PrePersist hook; never rewritten on subsequent updates.
updatedDate	integer	Unix timestamp the row was last touched. Bumped on every commit that hits the Doctrine UoW for this entity; drives FE invalidation + the listing change cursor.
passiveUpdatedDate	int	Read-through alias for `updatedDate` exposed under different serializer groups. Lets the FE distinguish "real edit" from "background touch" projections without changing the underlying column.
listingUpdatedDate	int	Listing-projection timestamp surfaced only under the `listMode` group. Driven by `TripCache` and other listing-shape refreshers separately from `updatedDate` so a listing rebuild doesn't trigger detail-page invalidation.