Service Areas

A Service Area is a top-level geographic boundary that defines where your operation runs. Service areas are stored as MultiPolygons — they can be a country outline, a metropolitan region, a delivery footprint, or any other named area — and they act as containers for one or more nested Zones.

Service areas are the foundation for:

• Geofencing — triggering on driver/vehicle entry, exit, dwell, and speeding (see Geofences)
• Zone-based pricing — service rates can be scoped to a service area or a specific zone within it (see Service Rates)
• Operational filtering — limit orders, drivers, and dispatch logic to a region

Concepts

Service areas have stable public IDs prefixed with sa_.

Managing Service Areas on the Map

Service areas (and the zones inside them) are managed from Fleet-Ops → Dashboard → Map tab. The map provider used to render tiles is governed by Map Settings.

There are two ways to drive service-area management from the map:

• The map toolbar — the icon strip on the left of the map. The service-areas icon opens a panel with creation, visual-control, and per-area action items.
• The right-click context menu — right-click anywhere on the map for a "Create new Service Area" entry, or right-click on an existing service-area polygon to get its contextual action menu (edit, edit boundaries, hide, delete, create zone inside, etc.).

Toolbar Panel

Click the service-areas icon in the map toolbar to open the panel. From the top:

Per-Area Context Menu

Right-click on a service-area polygon (or click its entry in the toolbar list) to get its actions menu:

Editing Boundaries

Choosing Edit Boundaries turns the polygon into a dashed outline with square handles at every vertex and midpoint. Drag a handle to reshape the boundary in place — no separate dialog, the change is committed on save.

Click outside the polygon or press the in-map cancel affordance to discard the change.

Creating a Service Area

From the toolbar's Create new Service Area entry (or the right-click context menu), Fleet-Ops switches the map into draw mode. Use the polygon tool in the draw controls to outline the area — click each vertex, then double-click (or click the first vertex again) to close the polygon. After you close the polygon, the creation modal opens with the boundary you just drew.

The creation modal asks for:

• Name
• Type (defaults to country)
• Country (selected from the country dropdown)
• Border color and Fill color

After saving, the new service area appears on the map and in the toolbar's service-area list. From there you can focus, hide, edit, edit boundaries, add zones, or delete it.

If you need to create service areas programmatically — from a radius around a point, or from a pre-drawn GeoJSON boundary — use the API instead. Those options are not exposed in the UI.

Hierarchies

Service areas support a parent/child relationship via parent_uuid. A typical hierarchy:

Country: United States (sa_abc…)
 ├── Region: West Coast (sa_def…)
 │    ├── State: California (sa_ghi…)
 │    │    └── City: San Francisco (sa_jkl…)
 │    └── State: Oregon (sa_mno…)
 └── Region: East Coast (sa_pqr…)

Use hierarchies when:

• Different management responsibilities apply at each level (e.g. a regional manager owns dispatch within a region, but pricing is set at the country level).
• You want to inherit defaults — child areas typically reuse the parent's country and visual style.

Skip the hierarchy when your operation is single-region — a flat list of service areas is easier to reason about.

Zones vs Service Areas

Create a service area first, then create zones inside it. See Zones.

API

All endpoints live under the FleetOps v1 API at /service-areas. Auth via your standard API key.

Create — Point + Radius

curl -X POST https://api.fleetbase.io/v1/service-areas \
  -H "Authorization: Bearer $FLEETBASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Singapore",
    "type": "city",
    "country": "SG",
    "latitude": 1.2839,
    "longitude": 103.8607,
    "radius": 5000,
    "color": "#3b82f6",
    "stroke_color": "#1d4ed8",
    "trigger_on_entry": true,
    "trigger_on_exit": true
  }'

The server generates a circular MultiPolygon with a 5 km radius around the point.

Create — Explicit Border

curl -X POST https://api.fleetbase.io/v1/service-areas \
  -H "Authorization: Bearer $FLEETBASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Footprint",
    "type": "region",
    "country": "SG",
    "border": {
      "type": "MultiPolygon",
      "coordinates": [[[[103.85, 1.28], [103.87, 1.28], [103.87, 1.30], [103.85, 1.30], [103.85, 1.28]]]]
    }
  }'

GeoJSON coordinate order is [lng, lat].

Nesting

Pass parent (the public ID of the parent service area) when creating:

{
  "name": "San Francisco",
  "parent": "sa_def_west_coast",
  "country": "US",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "radius": 25000
}

What's Next

• Subdivide a service area with Zones.
• Wire up entry/exit/dwell triggers in Geofences.
• Price orders differently by region with Service Rates.