Dispatch Zones

Taxi & Private Hire › Products › Dispatch › Dispatch Zones

Generally available

A Zone is a tenant-defined geographic area used by the dispatch engine. Zones have polygons (tested via point-in-polygon for trip pickups), reference labels, capacity-per-hour fallbacks, primary backup-group bindings, and optional region scoping. Drivers can be queued by zone (see Queues); zone selection drives the dispatch radius decision; analytics aggregate by zone.

Example request

POST /client/{clientId}/zone ▷ Try it

{
  "ref": "<string>",
  "name": "<string>",
  "primaryGroup": "<string>",
  "bounds": "<polygon>",
  "capacityPerHourFallback": 0,
  "proximityFallbackRadiusMetres": 0,
  "proximityFallbackMaxRadiusMetres": 0,
  "releaseBufferSeconds": 0,
  "proximityOfferTimeoutSeconds": 0,
  "region": {
    "id": "<id>"
  },
  "dispatchToSelf": "NONE",
  "backupZoneGroups": [
    {
      "id": "<id>"
    }
  ],
  "driverNote": "<string>",
  "managementNote": "<string>"
}

Example shape, derived from the Zone fields — indicative, not the authoritative schema (that arrives with the API reference).

Endpoints

Method	Path
POST	/client/{clientId}/zone · primary	▷ Try it
GET	/client/{clientId}/zone/{zoneId}	▷ Try it
GET	/client/{clientId}/zone/grouping	▷ Try it
POST	/client/{clientId}/zone/{zoneId}	▷ Try it

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

Use cases

Operator flows that exercise this feature.

Create a dispatch zone

config risk: low

Define a geographic dispatch zone (rank / queue area).

1. POST /client/{clientId}/zone

Related

• Driver Queues
• Backup Zones
• Zone Fallback Policy

Fields

Field	Type	Description
ref	string	Short tenant-defined zone reference / code ("AP", "T2"). Surfaces in the driver app and operator dispatch board; queryable via `queryFields()`. Pair with `name` for human-readable labels.
name	string	Friendly long-name for the zone ("Airport Terminal 1", "City Centre East"). Used in operator reporting and customer-facing surfaces; `ref` carries the short code.
primaryGroup	string	Primary group label for operator-side grouping (controller cluster, geographic team, depot binding). Surfaces on the dispatch board cuts and feeds reporting drill-downs.
bounds	polygon	GIS polygon defining the zone boundary. Point-in-polygon is run server-side against trip pickups to resolve `Trip.pickupZone`; the FE renders it via `UiMapRender`. Edit-mode MULTI because the polygon editor lives on its own tab.
h3Cells	json	Precomputed list of H3 cells (resolution 8) the polygon covers. Cached on save so H3-keyed lookups (RES-016 fleet metrics, scheduled-demand) can hit a tight index instead of running point-in-polygon repeatedly.
capacityPerHourFallback	smallint	Per-zone fallback capacity (transporters/hour) used by capacity-aware dispatch when live measured capacity is unavailable. Null = use the client-default policy.
proximityFallbackRadiusMetres	integer	Per-zone override for the base dispatch search radius (metres). Null falls back to the `dispatch.search_radius_metres` tenant parameter. Use to widen rural-zone search without bumping the default for everyone.
proximityFallbackMaxRadiusMetres	integer	Per-zone ceiling on the expanding-proximity radius (metres). Null falls back to `dispatch.allocation_risk.max_radius_metres`. Caps how far the dispatch engine will reach into neighbouring zones for this zone's trips.
releaseBufferSeconds	smallint	Additive offset (seconds) for pre-booked trip release timing in this zone. Lets sparse zones release earlier than dense zones. Null = no buffer.
proximityOfferTimeoutSeconds	smallint	Per-zone override for the dispatch-offer timeout (seconds) on trips picked up here. Null falls back to `dispatch.offer_timeout_asap_seconds`. Useful when one zone has chronically slower acceptance behaviour.
region	Region	Geographic region scope for tenant-level partitioning. `RegionFilter` restricts cross-region queries by this field; null = global within the tenant.
dispatchToSelf	DispatchMode · NONE | PROXIMITY | PROXIMITY_FAIRNESS | QUEUE	How trips that originate inside this zone get dispatched to drivers already inside the same zone: QUEUE (standard FIFO queue ordering) vs PROXIMITY (nearest-driver expanding-radius search). Pair with the backup-plan tabs for fallbacks when the in-zone supply runs dry.
backupZoneGroups	Collection	Backup zone groups that supply drivers to this zone when local supply is exhausted. Ordered by `priority` ASC — the dispatch engine walks groups in order, escalating into each only when prior tiers fail.
driverNote	string	Notes shared with the Driver and Operator, to be treated as publicly visible and not to include personal information
managementNote	string	Internal notes for management use only.
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.