A Tour Period is a time estimate in seconds of a service tour of for example a service employee who travels from location to location within a territory. The tour period is always calculated for exactly one territory. It is the sum of all service periods (see Service Period or activity values) at each location and all driving periods (see Driving Period) between locations this service employee passes through while providing service to customers in a territory.
A Service Period is the activity value of a location interpreted as time (in seconds) spent for providing service by an employee at a particular location.
A Driving Period is the server calculated time from one location to another within a territory. It is estimated by the average distance to a location's nearest neighbouring locations. The number of nearest locations can be configured in the PTV xTerritory's profile file (default.xml, see also the PTV xTerritory profile documentation).
The estimated driving time from a territory's centre to the territory itself is the average distance to the territory centre's nearest five locations. The estimated driving time to a territory cannot be configured and is not considered when a service period is calculated for a territory. It is however returned by the PTV xTerritory server in all uses cases except in the use case planTerritories.
Since activities of locations are numerical values with no strictly defined interpretation, they might as well represent service periods at locations:
ServicePeriodActivity class as activity value container.
Considering driving periods between locations as well as service periods at locations results in a rough service tour estimate for exactly one territory. The estimate serves one purpose; to be able to better plan calculated tours (PTV xTour server) in territories on the basis of such tour estimates by the PTV xTerritory server. The PTV xTerritory server is therefore able to consider these two time contributions for all three use cases - planTerritories(), distributeLocations(), changeTerritories() - for an estimate of a round trip service tour.
Due to the fact that driving times in rural areas contribute more to the total travel period (service period) of a service employee than in urban areas, the PTV xTerritory server allows for constraining tour periods by setting a single TourPeriodLimit for each territory. With this, a service tour period can be limited to, for example 8 hours of a typical work day. TourPeriodLimits can be applied in all three use cases: planTerritories(), distributeLocations() or changeTerritories() but .
Check if the following prerequisites are fulfilled before you start with one of the supported use cases.
PTV xTerritory server has been installed and the desired map is configured correctly.
A valid license for the individual use case: territory planning, location assignment and/or change territories has been provided.
Estimating tour periods for territories is a concept by which activity values of locations are interpreted as service periods, e.g. working hours of a service employee, and driving periods between locations are summed up. This sum then represents an estimated round trip time for a tour through all locations of a territory. This concept provides the basic mechanism for planning, distributing and changing territories according to a tour estimate. It can be regarded as a prior step for a more fine-grained tour calculation by the PTV xTour server with many more parameters. In general, for an estimate of a round trip tour period within a territory, service times and driving times are the only time contributions that are considered. The driving period from a territory centre to the territory itself is not considered by the PTV xTerritory's tour estimation. Nonetheless, this particular driving time is provided within the territory summary as additional value.
It is also possible to set limits with the PTV xTerritory server for each territory and all three use cases: territory planning, location assignment and change territories. If limits should be applied, the limit class TourPeriodLimit must be set to constrain the tour period estimation by a single value per territory (maximumDuration). A territory's estimated tour period then must not exceed this maximumDuration. A typical maximumDuration for a service tour period in a territory could be the maximum amount of eight working hours a day.
When limiting tour periods, TourPeriodLimit must not be mixed with AbsoluteActivityLimits.
Limiting the duration of a tour period for a territory can have a major impact on the calculation results in all use cases. However, when limits are applied, it can become impossible to find a valid calculation result. If this occurs, more reasonable values for the limits themselves or other planning parameters within the planningProfile need to be considered.
For further information on how to use activity limits (or tour period limits) see the use case How to distribute locations with predefined limits.
In order to balance tour periods instead of absolute activity sums, the following is required:
Territory objects, locations can be assigned/are assigned to (not necessary for territory planning).
When using tour estimation, AbsoluteActivities must not be mixed with ServicePeriodActivities.
ServicePeriodActivities
When balancing tour periods per territory, a location's activity is interpreted as service period in seconds. Therefore, the class ServicePeriodActivity has to be set for each location.
"locations": [
{
"id": "location1",
"coordinate": {
"point": {
"x": 6.166279,
"y": 49.629301
}
},
"activity": {
"$type": "ServicePeriodActivity",
"period": 100
}
},
{
"id": "location2",
"coordinate": {
"point": {
"x": 0.166279,
"y": 0.629301
}
},
"activity": {
"$type": "ServicePeriodActivity",
"period": 100
}
}
]
If territories already exist and should be used to assign locations to them, they need to be set within the request to the PTV xTerritory server as well.
"territories": [
{
"id": "territory1",
"referencePoint": {
"point": {
"x": 6.424008,
"y": 49.704545
}
}
},
{
"id": "territory2",
"referencePoint": {
"point": {
"x": 12.848016,
"y": 49.704545
}
}
}
]
A complete JSON sample request (distributeLocations or changeTerritories)
{
"locations": [
{
"id": "sampleLocation1",
"coordinate": {
"$type": "Point",
"point": {
"$type": "PlainPoint",
"x": 675000,
"y": 6380000
}
},
"activity": {
"$type": "ServicePeriodActivity",
"period": 100
}
},
{
"id": "sampleLocation2",
"coordinate": {
"$type": "Point",
"point": {
"$type": "PlainPoint",
"x": 675500,
"y": 6380500
}
},
"activity": {
"$type": "ServicePeriodActivity",
"period": 100
}
},
{
"id": "sampleLocation3",
"coordinate": {
"$type": "Point",
"point": {
"$type": "PlainPoint",
"x": 676000,
"y": 6381000
}
},
"activity": {
"$type": "ServicePeriodActivity",
"period": 100
}
},
{
"id": "sampleLocation4",
"coordinate": {
"$type": "Point",
"point": {
"$type": "PlainPoint",
"x": 676500,
"y": 6381500
}
},
"activity": {
"$type": "ServicePeriodActivity",
"period": 100
}
}
],
"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"
},
"responseContents": {
"territories": true,
"locations": true
},
"callerContext": null
}
The response with estimated tour periods for each territory is very similar to use cases where AbsoluteActivity was used. The main difference is that driving periods from location to location are also taken into account for the estimated tour period in each territory. Therefore, the totalActivity of each territory does not represent the sum of each location's activity but the sum of all service periods added to the sum of all driving periods in this territory. The estimatedTravelTimeToTerritory can be obtained from the TerritorySummary in the PTV xTerritory server's response.
Copyright © 2024 PTV Logistics GmbH All rights reserved. | Imprint
