Use Cases > Cluster Planning > How to plan territories > ... with predefined groups

How to plan territories with predefined groups

Predefined groups ensure that certain objects can be kept together during cluster respectively territory planning. Locations in the same group can be assigned to any territory, but only together and all to the same territory. This means that the group must not be broken up. A typical use case is territory planning according to postcode. Customers who live in the same postcode should not be assigned to different employees.

Groupings can be used for both territory planning and for location assignment, because a group is not assigned to a particular territory.

Grouping can, under certain circumstances, have a major impact on the planning result. It can become impossible to find a valid result. If this occurs, the tolerance threshold may have to be altered.

Terminology

group: Group of locations which can only be assigned to a territory collectively.

Benefits

During territory planning, groups of locations are taken into account which belong together and thus cannot be divided up across multiple territories.

Prerequisites

Check if the following prerequisites are fulfilled before you start with the use case.

PTV xTerritory server has been installed
High-performance routing network for calculating routes, if applicable.

Concept

Bringing individual customers together in predefined groups can easily have an external impact on the PTV xTerritory server's planning result. It means that a customer group can be assigned to any territory, but not split to different territories. The fixed assignment of individual customers to particular territories is explained further in the use case fixed assignments. Predefined groups can mean that sub-optimal results are produced, or even that it becomes impossible to find a valid solution. In order to prevent this, one can, for example, increase the value specified for tolerance of imbalanced territories (imbalanceTolerance).

Which location belongs to which group is determined by the group name. That said, group names can be chosen freely. Locations with the same group name will be assigned to the same group, and thus to the same territory.

Not all locations need to have a group name. Locations which do not clearly belong to a group will be planned as usual.

Configuration Guide

In addition to the digital map of the area which contains the locations, a license is required for the planTerritories method and/or for distributeLocations, in the case of location assignment, as well as for the desired number of territories and locations.

If high-performance routing networks are to be used, a license must also be obtained for these. Furthermore, the path to the Routing Network folder must be placed accordingly in conf/xterritory.properties.

Programming Guide

In order to carry out territory planning or location assignment, the following are required:

locations and their groupings
parametrisation for the calculation of stretches of route
Number/territory centres of territories to be planned

Set locations

Each location to be planned will be represented by an id and a coordinate.

Moreover, an activity must also be given for each location, since the aim of territory planning is to calculate territories such that they are as balanced as possible. For simple activity measures the class AbsoluteActivity is used, of which the value contains a double value which is simply totalled for each territory during territory planning.

Location groups can be identified by the identical group names (group attribute in the element LocationProperties). The group name can be chosen freely. When grouping by postcode, the postcode can make a good group name:

"locations": [
  {
    "id": "location1",
    "coordinate": {
      "point": {
        "x": 6.166279,
        "y": 49.629301
      }
    },
    "activity": {
      "$type": "AbsoluteActivity",
      "value": 3.0
    },
    "properties": {
      "group": "76131"
    }
  }
]

Since the location coordinates are in geodecimal format here, the coordinate format must also be specified in the request, in the CallerContext.

Parametrisation for the calculation of stretches of route

PTV xTerritory server offers several ways to calculate stretches of route:

As the crow flies (ApproximateByDirectDistance)
Distances by road (NewDistanceMatrixByRoad)
Use of previously calculated routes (ExistingDistanceMatrixByRoad and ApproximateByReferenceMatrix)

The respective option will be chosen according to the DistanceCalculationOptions subclass that is instantiated.

Example for NewDistanceMatrixByRoad:

"distanceCalculationOptions": {
  "$type": "NewDistanceMatrixByRoad"
}

Number of territories to be planned

During territory planning, the precise number of territories to be planned must be specified in the PlanningOptions.

"planningOptions": {
  "exactNumberOfTerritories": 2
}

During location assignment, the number of territories is determined by the number of territory centres and must be transferred as a list of territories.

"territories": [
  {
    "id": "territory1",
    "referencePoint": {
      "point": {
        "x": 6.424008,
        "y": 49.704545
      }
    }
  }
]

Manage response contents

In the request element ResponseContents, two types of result lists can be switched on or off. Generally, a list of territories and their assigned locations will be returned. Instead of (or in addition to) this, the parameter locations lets you switch on a list of locations in the response. The locations in the response are in the same order as in the request and the assigned territory is also shown for every location (Location.territoryId). A list of locations can be used in a follow-up request, for example, to set fixed assignments of individual locations to particular territories (see use case fixed assignments). Both lists do contain redundant information, but this enables clients to choose the list which is most efficient for them.

If a list of territories is not provided in the response, there is no way of finding the reference points of individual territories for the purpose of territory planning.

"responseContents": {
  "territories": false,
  "locations": true
}

Objects in the response

Because territories was set to false and locations was set to true in the ResponseContents element in the request, a list of locations is included in the response instead of a list of territories. Each location still has a unique identifier in the form of its id. Assignments to individual territories can be made using the territoryId, which is now set for all locations. Membership of a group is also displayed the same way in the response as in the request, i.e. via the group attribute in the properties element.

"locations": [
  {
    "id": "location1",
    "coordinate": {
      "$type": "Point",
      "point": {
        "$type": "PlainPoint",
        "x": 6.166279,
        "y": 49.629301
      }
    },
    "activity": {
      "$type": "AbsoluteActivity",
      "value": 2
    },
    "properties": {
      "group": "76131"
    },
    "territoryId": "1"
  }
]

If a distance matrix has been calculated or expanded in the request (NewDistanceMatrixByRoad or ExistingDistanceMatrixByRoad) a DistanceMatrixSummary element is included in the response. Among other things, it provides an id for the distance matrix, which can be entered in the ExistingDistanceMatrixByRoad element in any further requests, in order to reuse the distance matrix which had just been calculated.