Time Windows

Taxi & Private Hire › Products › Trip › Time Windows

Generally available

Per-stop time windows constrain when a pickup or dropoff may happen — a customer's "between 9 and 10am at the school", a contract SLA, and so on. They are treated as hard constraints during route scheduling, and used up front to group only trips that can actually be served together.

Related

• Trip Stops
• Trip Optimizer
• Multi-Load Trips

Fields

Field	Type	Description
pickupAddress	string	Human-readable address text for this stop. Required. Picked via the address-search autocomplete which forward-maps the coords + provider ID onto the sibling fields below.
pickupAddressId	string	Geocoder reference ID (Google Places ID where available) for the picked address. Lets later operations re-resolve the canonical address + components without redoing the search.
pickupLatitude	decimal	WGS-84 latitude. Required + price-sensitive — drives routing, zone resolution, and tariff selection. Editing re-quotes the segment.
pickupLongitude	decimal	WGS-84 longitude. See pickupLatitude.
note	string	Free-text note shown to the driver at this stop — gate codes, side-entrance directions, "ring bell 3", etc.
tripSegment	TripSegment	Parent segment. Each stop belongs to exactly one TripSegment.
tripSegmentId	string	Materialised parent segment ID (G-prefixed JSON / BIGINT in DB). Convenience for the driver-app sync payload — avoids hydrating the full parent for the common case.
sequence	smallint	Visit order within the parent segment (1-indexed). Pickup first, then any intermediate waypoints, then dropoff. Reordering is price-sensitive.
type	TripSegmentStopType · PICKUP | DROPOFF | VISIT	Stop role: PICKUP, DROPOFF, or WAYPOINT. Drives ETA rules (PICKUP starts the meter), capacity bookkeeping (PICKUP adds, DROPOFF subtracts), and the SaveCustomerAddress side-effect (PICKUP increments usedPickupCount).
status	TripSegmentStopLifecycleEnum · NONE | SCHEDULED | ENROUTE | ARRIVED | FINISHED | NOSHOW | CANCELLED	Per-stop lifecycle: NONE → SCHEDULED → ENROUTE → ARRIVED → FINISHED, with NOSHOW / CANCELLED as terminal alternates. Each transition flows through guards (proximity, wait-time, etc.).
tripUnitOfWork	TripUnitOfWork	The Unit of Work bucket this stop belongs to — co-located stops within ~50m share a UoW. Driver app processes stops grouped by UoW rather than one-at-a-time.
tripSegmentChargeableItems	Collection
passengerCapacityRequirement	smallint	Passenger count joining (PICKUP) / leaving (DROPOFF) at this stop. Drives the capacity-balance check across the segment + our optimisation engine's capacity dimension.
luggageCapacityRequirement	smallint	Luggage-item count moving at this stop. Mirrors passengerCapacityRequirement on the luggage axis — feeds the same capacity-balance check.
windowStart	integer	Earliest acceptable arrival at this stop (unix). Null = no constraint. our optimisation engine treats the (windowStart, windowEnd) pair as hard time-window bounds during optimisation.
windowEnd	integer	Latest acceptable arrival at this stop (unix). Null = no upper bound. School-run + medical-appointment trips set this aggressively.
arrivedLatitude	decimal	Latitude the driver was actually at when they marked the stop arrived. Recorded alongside the booked lat/lng for dropoff-coord-mismatch detection.
arrivedLongitude	decimal	Longitude the driver was actually at when they marked the stop arrived. See arrivedLatitude.
arrivedDate	integer	Unix timestamp the driver marked this stop as ARRIVED. Combined with windowStart/End to compute lateness; pairs with arrivedLatitude/Longitude for the recorded arrival location.
callAttempts	smallint
lastCallAttemptDate	integer
targetStop	TripSegmentStop
zone	Zone
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.