How to change territories

If you already have conducted a territory planning, you can change it by altering the number of territories while using all or some of your previous territory centres. Different territories with new location assignments are created. This use case complements the use cases

Benefits

With the PTV xTerritory server's changeTerritories feature you can

• plan territories again by requesting more territory centres and keep the old ones.

• plan territories again marking existing territory centres or new ones as candidates.

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 the extension of existing territories by adding new ones. Territory centres can be marked as candidates for the planning and additional locations can be provided. All territory centres that are not explicitly marked as candidates will be kept in the result.

Configuration Guide

Aside from the digital map of the area in which the locations are sited, a license is required for the changeTerritories 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 territory change, the following are required:

• Locations

• Territories (territory centres)

• Number of territories to be planned

• Parametrisation for the calculation of stretches of route

A complete description of these parameters can be found in the use cases

Basically when changing territories, it is allowed to set territory candidates that are then subject to change. However, it is not allowed to reference these candidate territories by limits via their territoryAssignment property since candidate territories could be vanished after the changeTerritories() method has been requested. This would leave still assigning limits unassigned if they referenced such "disposable territories" (candidates) before the changeTerritories() method was requested. It is only allowed that limits carry territory assignments to fixed territories or even carry an empty territory assignment.

complete JSON request

{
  "locations": [
    {
      "id": "sampleLocation1",
      "coordinate": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 675000,
          "y": 6380000
        }
      },
      "activity": {
        "$type": "AbsoluteActivity",
        "value": 1
      },
      "territoryId": "sampleTerritory1"
    },
    {
      "id": "sampleLocation2",
      "coordinate": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 675500,
          "y": 6380500
        }
      },
      "activity": {
        "$type": "AbsoluteActivity",
        "value": 1
      },
      "territoryId": "sampleTerritory1"
    },
    {
      "id": "sampleLocation3",
      "coordinate": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 676000,
          "y": 6381000
        }
      },
      "activity": {
        "$type": "AbsoluteActivity",
        "value": 1
      },
      "territoryId": "sampleTerritory2"
    },
    {
      "id": "sampleLocation4",
      "coordinate": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 676500,
          "y": 6381500
        }
      },
      "activity": {
        "$type": "AbsoluteActivity",
        "value": 1
      },
      "territoryId": "sampleTerritory2"
    }
  ],
  "territories": [
    {
      "id": "sampleTerritory1",
      "referencePoint": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 676750,
          "y": 6381550
        }
      }
    },
    {
      "id": "sampleTerritory2",
      "referencePoint": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 676250,
          "y": 6381250
        }
      }
    }
  ],
  "distanceCalculationOptions": {
    "$type": "ApproximateByDirectDistance"
  },
  "planningOptions": {
    "exactNumberOfTerritories": 4
  },
  "planningProfile": null,
  "responseContents": null,
  "callerContext": {
    "properties": [
      {
        "key": "CoordFormat",
        "value": "PTV_MERCATOR"
      },
      {
        "key": "Profile",
        "value": "default"
      }
    ]
  }
}

Objects in the response

{
  "territories": [
    {
      "id": "sampleTerritory1",
      "referencePoint": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 676745.32404,
          "y": 6381546.2771
        }
      },
      "summary": {
        "totalActivity": 1,
        "numberOfLocations": 1
      },
      "locationIds": [
        "sampleLocation4"
      ]
    },
    {
      "id": "sampleTerritory2",
      "referencePoint": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 676249.94111,
          "y": 6381248.0855
        }
      },
      "summary": {
        "totalActivity": 1,
        "numberOfLocations": 1
      },
      "locationIds": [
        "sampleLocation3"
      ]
    },
    {
      "id": "1",
      "referencePoint": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 675499.6524,
          "y": 6380497.7968
        }
      },
      "summary": {
        "totalActivity": 1,
        "numberOfLocations": 1
      },
      "locationIds": [
        "sampleLocation2"
      ]
    },
    {
      "id": "2",
      "referencePoint": {
        "$type": "Point",
        "point": {
          "$type": "PlainPoint",
          "x": 674999.45993,
          "y": 6379997.6043
        }
      },
      "summary": {
        "totalActivity": 1,
        "numberOfLocations": 1
      },
      "locationIds": [
        "sampleLocation1"
      ]
    }
  ]
}

Copyright © 2024 PTV Logistics GmbH All rights reserved. | Imprint