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_limitations: This field models the service capacity of a location, such as the maximum number of vehicles that can be dispatched per hour. It directly implements the Cumulative Limitation constraint for that specific location when it's used as a pickup point.

• 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_limitations and service_time, the values are simply inherited from the group if they are not explicitly defined at the location level.

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.