Skip to content
Honeywick Consulting

surgeZoneObject

A surge zone raises an alert level (e.g. RED / AMBER / GREEN) for a named surge domain over a geographic region. Since Spiral 2.4.0a the zone no longer carries its own effects: it names a domain and an alert, and the actual factors are authored per stop / resource type in the domain file (see Surge domain / alert model below). Every stop or resource whose type declares a matching domain block has that block’s factors for the current alert applied while it lies within the zone.

{
"id": <integer>,
"domain": <string>,
"alert": <string>,
"zone": <zone> | null,
"innerRadius": <distance> | null,
"active": <bool> | null,
"seqno": <integer> | null,
"color": <string> | null,
"ext": <object> | null,
}
id integer
Unique identifier for the surge zone.
domain string
The surge domain this zone drives — a domain name declared by stop / resource types via their `domain` blocks (and listed in helix.domains). Sent to Spiral.
alert string
The alert level in force for the domain (conventionally "RED" / "AMBER" / "GREEN"; the schema accepts any level a domain declares). GREEN conventionally carries no factors — i.e. no effect. Sent to Spiral.
zone zone
The circular region { centre, radius } the alert applies to. Only the centre position is sent to Spiral. null / absent = a "blanket" zone applied everywhere (and never drawn on the map).
innerRadius distance
The effect is constant within the inner radius and interpolates to none at the zone’s outer radius. null for a blanket zone.
active bool
Switches the zone on / off within Spiral (replaces the former `surge` flag).
seqno integer
Helix-only — optimistic-lock sequence number (a missing value reads as 0, so older records heal on first edit).
color string
Helix-only — a colour-palette name or CSS value used to render the zone on the map; never sent to Spiral. When unset the alert’s traffic-light colour is used.
ext object
Helix-only — client extension metadata; never sent to Spiral.

Surge domain / alert model

Section titled “Surge domain / alert model”

A surge zone is only the trigger. The effects are authored per stop / resource type in the domain file, as a top-level domain block on stopParams / resourceParams:

"domain": {
  "Road": {                                  // a surge domain (also listed in helix.domains)
    "AMBER": { "priority": 1.0, "ATA": 1.0 },  // factors while an AMBER zone for "Road" is active
    "RED":   { "priority": 0.1, "ATA": 1.5 }
  }
}

When a live surge zone names { "domain": "Road", "alert": "RED" }, every stop / resource whose type declares domain.Road has that domain’s RED factors applied within the zone — constant inside innerRadius, interpolating to none at the zone’s outer radius (blanket zones apply everywhere). The factor keys differ by side:

  • Stop-side (stopParams.domain): priority and ATA — reweight the stop’s scheduling priority and arrival-time allowance.
  • Resource-side (resourceParams.domain): travel and demand — scale the resource’s travel cost and expected demand.
// resourceParams surge block (resource-side factors)
"domain": {
  "Road": {
    "AMBER": { "travel": 2.0, "demand": 2.0 },
    "RED":   { "travel": 3.0, "demand": 10.0 }
  }
}

The domain is one namespace shared by stops and resources. Authoring a factor on the wrong side (a resource factor on a stop type, or vice-versa) is flagged with a warning at domain-seed time. GREEN is normally omitted, meaning “no effect”. Projects are surge-domain-less — they inherit their initial stop’s domain. See the guide for how the domain name also groups skills: Develop a client extension.

Section titled “Related”