Customer master

SWAT model supports synchronization, storing, management and automatic hydration of Location Master into the incoming booking. The purpose of the Location Master is to reduce the burden on the consuming application to storing coordinates, timewindows and other Location master related information. On upload, if a booking has a value set in booking.pickup_operations_location (or external_id), information from corresponding location will be automatically added to a booking, including:

• Latitude and Longitude
• Name
• Time windows
• Service times
• Additional contraints if any (for example, vehicle type)

Mutual Exclusivity

When defining a pickup or dropoff location, you must use either explicit coordinates (pickup_location_lat/lon) or an operations location reference (pickup_operations_location URI or pickup_operations_location_external_id). You cannot provide both; doing so will result in a validation error. The same rule applies to dropoff locations.

Location master is represented by three entities:

• Operations Location
• Operations Location Time windows
• Operations Location Groups

Location master is integrated into the processing pipeline allowing referencing location master objects in booking\orders on upload.

Calculation Parameters

Both OperationsLocation api and OperationsLocationGroup api models support a calculation_params object. This object allows you to define specific optimization parameters that are automatically applied when a booking references that location or a location from that group.

These parameters are used to model real-world constraints and operational details, such as:

• Time required to enter or exit a facility (e.g., warehouse, secure compound).
• The service capacity of a location (e.g., how many vehicles can be loaded at once).
• Dynamic service times based on the type and quantity of goods.

Relationship with Compound Zones and Cumulative Limitations

The calculation_params object provides a convenient way to implement the concepts of Compound Zones and Cumulative Limitations at the location level.

• enter_time & exit_time: These fields directly create a Compound Zone. When a vehicle's route includes a location with these parameters set, the specified time is added as a penalty for entering and exiting the location. This is ideal for modeling warehouse docking times or security gate clearance.

• cumulative_limitation: This field models the service capacity of a location, such as the maximum number of vehicles that can be dispatched per hour. It takes a depot_service_time and a max_cumulative_vehicles, and directly implements the Cumulative Limitation constraint for that specific location when it's used as a pickup point.

  It cannot be combined with the simulation-wide max_departures_per_hour setting: an optimization that has both a max_departures_per_hour value and a location or group carrying its own cumulative_limitation fails rather than choosing between them.

• service_time & coefficients: These fields allow for sophisticated service time calculations. You can set a fixed per-order service time and add a dynamic component based on the booking.product_kind and its demand.

  When a booking is processed at an operations location with these parameters, the total service time is calculated as follows:

  Total Service Time = service_time.fixed + (booking.demand.cbcm * coefficients[product_kind].cbcm) + (booking.demand.weight * coefficients[product_kind].weight) + ...

  The coefficients object contains keys that match the booking.product_kind. Each product_kind key then contains another object where keys match the demand types (e.g., cbcm, weight) and values are the multipliers for that demand.

  For example, if you have a calculation_params object like this:

  "calculation_params": {
    "service_time": { "fixed": 300 },
    "coefficients": { "AMBIENT": { "cbcm": 0.000018, "weight": 0.01 } }
  }

  And a booking with product_kind: "AMBIENT" and demand: { "cbcm": 500000, "weight": 100 }, the service time will be: 300 + (500000 * 0.000018) + (100 * 0.01) = 300 + 9 + 1 = 310 seconds.

Inheritance and Grouping Logic

Parameters can be set at both the OperationsLocationGroup (area) level and the individual OperationsLocation level.

• If calculation_params are not set on an individual OperationsLocation, they are inherited from the OperationsLocationGroup it belongs to.
• If set at both levels, both settings are applied cumulatively (nested application). See Compound Zone for details.

warning

When enter_time or exit_time are set at the OperationsLocationGroup level, all locations belonging to that group are treated as a single compound zone. This means the entry and exit time penalties are applied only once for the entire group of locations within a vehicle's route, not for each individual location.

If you need to apply entry/exit times to each location separately, you must define these parameters on each OperationsLocation object individually.

Also, note that if at least one value for enter_time or exit_time is set, then both must be not null; otherwise, both must be null.

For cumulative_limitation and service_time, the values are simply inherited from the group if they are not explicitly defined at the location level.

A location can also be assigned an Operations Location Category, which carries its own calculation_params and takes precedence over the values set on the location itself.

Parameters are re-resolved on every optimization run

Hydration at upload time is not the only moment a location's parameters reach a booking. Each optimization run re-resolves the effective calculation_params for every booking it touches — including bookings whose nodes are already assigned to a vehicle in that run, not just the ones being uploaded or re-planned.

So editing a location, a group, or a category takes effect on the next optimization run for work already on the road, without needing the affected bookings to be re-uploaded.

Per-Node-Type Parameters

Starting with version 1.9.4.rc.593 (SP2-144), calculation_params supports node-type-specific overrides. This means you can define different service times, coefficients, and time offsets for pickup, dropoff, and point nodes at the same operations location.

The following fields accept optional nested objects with pickup, dropoff, and point keys (each using the same structure as calculation_params):

Field	Description
pickup	Overrides applied when the location is used as a pickup node
dropoff	Overrides applied when the location is used as a dropoff node
point	Overrides applied when the location is used as a point node

Resolution Order

When calculating parameters for a node, the system uses this fallback chain:

1. Check if the node-type-specific field is set on the individual OperationsLocation (e.g., calculation_params.pickup)
2. Otherwise, check the same node-type-specific field on the OperationsLocationGroup
3. If no node-type-specific override exists, fall back to the base calculation_params values

This means you can set general defaults at the base level and only override specific values for certain node types.

Examples

Example 1: Different service times per node type (warehouse with loading dock)

A warehouse where loading goods onto a truck (pickup) takes longer, while delivery drop-offs are quick:

{
  "calculation_params": {
    "service_time": {
      "fixed": 180
    },
    "pickup": {
      "service_time": {
        "fixed": 300
      },
      "coefficients": {
        "AMBIENT": { "cbcm": 0.000015 },
        "CHILLED": { "cbcm": 0.000025, "weight": 0.005 }
      }
    },
    "dropoff": {
      "service_time": {
        "fixed": 120
      }
    }
  }
}

In this example:

• Pickup nodes get 300s fixed service time + demand-based coefficient
• Dropoff nodes get 120s fixed service time (no coefficients)
• Point nodes (and any node type without explicit override) inherit the base 180s

Example 2: Time window offsets for depot operations

A distribution center where pickup nodes should have a wider time window (open earlier, close later) to accommodate pre-loading:

{
  "calculation_params": {
    "open_ts_offset": { "fixed": 0 },
    "close_ts_offset": { "fixed": 0 },
    "pickup": {
      "open_ts_offset": { "fixed": -1800 },
      "close_ts_offset": { "fixed": 1800 }
    },
    "dropoff": {
      "open_ts_offset": { "fixed": 300 },
      "close_ts_offset": { "fixed": -300 }
    }
  }
}

In this scenario:

• Pickup nodes: Open 30 min earlier (-1800s), close 30 min later (+1800s) → wider window
• Dropoff nodes: Open 5 min later (+300s), close 5 min earlier (-300s) → tighter window
• Point nodes: Use base values (0, 0)

info

Time window offsets require enable_time_windows_adjustment to be set to true in your simulation settings.

Example 3: Compound zones with per-type entry/exit times

A large industrial park where trucks enter through a security gate for pickups (longer security check) but drop-offs use a separate express lane:

{
  "calculation_params": {
    "enter_time": { "fixed": 120 },
    "exit_time": { "fixed": 60 },
    "pickup": {
      "enter_time": { "fixed": 300 },
      "exit_time": { "fixed": 180 }
    },
    "dropoff": {
      "enter_time": { "fixed": 60 },
      "exit_time": { "fixed": 30 }
    }
  }
}

In this case:

• Pickup nodes: 5 min to enter (security + loading dock check), 3 min to exit
• Dropoff nodes: 1 min to enter (express lane), 30 sec to exit
• Point nodes: Base 2 min enter, 1 min exit
• Nodes of different types at this location will be placed into separate compound zones

Example 4: Full override at the group level with location-level refinements

Setting defaults at the OperationsLocationGroup level and overriding only specific node types at the location:

{
  "OperationsLocationGroup": {
    "calculation_params": {
      "service_time": { "fixed": 200 },
      "pickup": {
        "service_time": { "fixed": 400 },
        "coefficients": { "AMBIENT": { "cbcm": 0.00001 } }
      },
      "dropoff": {
        "service_time": { "fixed": 150 }
      }
    }
  },
  "OperationsLocation": {
    "calculation_params": {
      "pickup": {
        "service_time": { "fixed": 500 },
        "coefficients": {
          "CHILLED": { "cbcm": 0.00002, "weight": 0.008 }
        }
      }
    }
  }
}

Here, this particular OperationsLocation:

• Pickup nodes: Inherits dropoff: { service_time: { fixed: 150 } } from group, but overrides its own pickup with 500s + CHILLED coefficients. AMBIENT coefficient does NOT carry over — the entire pickup object is replaced.
• Dropoff nodes: Inherits from group (150s fixed).
• Point nodes: Inherits general base from group (200s fixed).

The same per-node-type override logic applies to:

• service_time.fixed
• coefficients
• enter_time.fixed
• exit_time.fixed
• open_ts_offset.fixed
• close_ts_offset.fixed

Compound Zones Per Node Type

When enter_time or exit_time is defined with per-node-type overrides, compound zones are computed separately per node type. Nodes of different types at the same location will be grouped into separate compound zones, each with its own entry/exit times.

By leveraging calculation_params, you can build a rich and accurate model of your operational locations, which simplifies the process of creating bookings and ensures that the optimization engine respects your real-world constraints.

Operations Location Categories

A category api is a project-scoped label that carries its own calculation_params. Where a group answers "which locations are served together", a category answers "which locations behave the same way" — for example chilled dock, residential or secure compound. It lets you maintain one set of service times, entry/exit times and cumulative limitations for all such locations instead of repeating the values on each one.

A category holds a name, an optional external_id, a free-form data object and calculation_params.

Assigning a category

Categories attach to locations through an assignment api that links a location, a category and an optional simulation:

• Default assignment (no simulation) — the category the location uses in every simulation. A location can have at most one.
• Simulation assignment — overrides the default inside a single simulation. A location can have at most one per simulation.

Both the category and the simulation must belong to the same project as the location.

tip

The operations_location.default_category_id field reports the category of the default assignment. It is maintained by the system whenever assignments change, so you set it by creating or removing an assignment rather than by writing to the field. The add_update_operations_location bulk task exposes it as a writable shortcut that manages the default assignment for you.

Precedence

For a given location in a given simulation, calculation_params are resolved by taking the first source that exists. The sources are not merged:

1. Simulation-scoped calculation parameters for the location
2. The category assigned to the location for that simulation
3. The category assigned to the location as its default
4. The location's own calculation_params
5. The group's calculation_params

caution

An assigned category outranks the location's own calculation_params — it is not a fallback used only when the location has none. Assigning a category to a location that already carries its own parameters replaces them.

Presence is what counts, not content: a category whose calculation_params are empty blanks out the parameters for that location rather than falling through to the location or group values. To let a location keep its own parameters, do not assign it a category.

Invalidated categories are skipped during resolution, and deleting a category clears it from every location that referenced it.