Use Cases > Cluster Planning > How to distribute locations

How to distribute locations

In certain cases, as well as the locations, the number and position of the territory centres is already known. It is then a case of location assignment (distributeLocations). The aim is to create as even a distribution of locations across individual territory centres as possible, which can, for example, also be represented by a sales representative's apartment.

Benefits

With the PTV xTerritory server's distributeLocations feature, locations can be spread evenly across given territory centres.

Planning balanced territories e.g. according to revenue potential, number of households.
Fair distribution of labour across a variety of sales representatives.
Creating territories which are geographically compact, based on actual kilometres of road and travel times, to reduce travel time and maximise time with the customer.

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

This use case describes location assignment. In addition to the locations, the number and position of the territory centres is already known. Still to be ascertained is the assignment of locations to the territory centres, which will allow the size and shape of the territories to be determined.

Analogous to the territory planning, during location assignment with absolute activities the activity total is displayed for each territory and the locations are spread across the territories accordingly.

The target criteria balance, contiguity and compactness are also analogous to the territory planning. There is a more precise description of the target criteria in the use case planTerritories

Configuration Guide

Aside from the digital map of the area in which the locations are sited, a license is required for the distributeLocations method and 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

To carry out a location assignment, the following is required:

Locations
Territories (territory centres)
Parametrisation for the calculation of stretches of route

When distributing locations, keep in mind that candidate territories cannot be used.

Set locations

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

Furthermore, an activity must be provided for each location, since the aim of location assignment is to create territories which are as balanced as possible. For simple activity measures, the class AbsoluteActivity is used, the value of which contains a double value that is then simply totalled for each territory during the location assignment process.

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

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

Set territories/territory centres

During location assignment, the territory centres must have been entered previously in the request, and will not be altered by the planning algorithm. A territory center is modelled as a territory, in the sense that every territory is represented by a reference point, in this case the territory center.

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

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 ApproximateByDirectDistance:

"distanceCalculationOptions": {
  "$type": "ApproximateByDirectDistance"
}

Manage response contents

In the request element ResponseContents, two types of result lists can be switched on or off. Generally, a list of territories with 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, for example, be used in a follow-up request to create 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.

"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 are identified using the territoryId, which is now set for all locations.

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