Use Cases > PTV xMap > How to Use Feature Layer Theme PTV_TimeZones

How to Use Feature Layer TimeZones

The Feature Layer PTV_TimeZones enables you to use time zone information at each point of your route

This layer provides time zone information at a given location. This information is necessary to consider time dependent restrictions correctly in the route planning. For example temporary road closures and road works. Different time zones can be considered in routing and estimated time of arrival ETA calculation. Time zones can be precisely displayed, especially in connection with historical traffic information and traffic patterns.

Terminology

Check these terms to ensure you understand the whole use case.

Feature Layer: The Feature Layer defines the additional data mechanism. The data is partitioned into several themes that characterise different use-cases.

Benefits

Using TimeZones you can ...

calculate the arrival time at each waypoint in its local time zone.
localise time zone changes exactly along the route

Prerequisites

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

PTV xRoute Server and a digital map of the area for route calculation.
Installation of Feature Layer "PTV_TimeZones". The usage of this Feature Layer in conjunction with PTV xRoute Server is available in version 1.17 or higher. UTC offset information can be requested since version 1.18.1.
In order to request information from the feature layer theme PTV_TimeZones with the PTV xRoute Server, you need to ensure that the following licence key includes the theme PTV_TimeZones
```
                xroute.featureLayerThemes=PTV_TimeZones, ...
```

Displaying time zone information is only supported by methods that return segments or waypoints in their result list: calculateRoute, calculateExtendedRoute, calculateTour and calculateAdvancedTour.

Concept

Feature layers are designed to provide various additional data to the user. The content depends on the feature layer theme and can be configured via XML profile. In the PTV xRoute server, feature layer data can be requested as generic FeatureDescription element for each route segment.

For PTV_TimeZones this feature description element contains time-independent time zone information in gdf time domain format. This format is difficult to parse, therefore PTV xRoute provides an additional parameter to request the offset from UTC time for each route segment or waypoint.

Installation Guide

Download the latest feature layer TimeZones from the Customer Area according to the used map. If you do not have an account, please contact your account manager at PTV.
Unzip the PTV_TimeZones_<Mapname>.zip file directly to the map folder of the PTV xRoute Server. The map folder is specified in the maps.path key of the configuration file <PTV xRoute folder>/conf/xroute.properties.
Restart the PTV xRoute Server to activate the just installed feature layers.

Programming Guide

Use a routing request (calculateRoute or calculateExtendedRoute) or a tour request (calculateTour or calculateAdvancedTour) with at least two stations and enable the use of the feature layer theme PTV_TimeZones by setting the following XML profile snippet in the CallerContext.

<Profile xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
 <FeatureLayer majorVersion='1' minorVersion='0'>
  <!--enable the time dependency because we are using the time dependent theme PTV_TimeZones-->
  <GlobalSettings enableTimeDependency='true'/>
  <Themes>
   <!--enable the PTV_TimeZones theme-->
   <Theme id='PTV_TimeZones' enabled='true'/>
  </Themes>
 </FeatureLayer>
  <Routing majorVersion='2' minorVersion='0'>
   <Course>
    <!--enable additional data rules to enable routing with additional content like feature layer-->
    <AdditionalDataRules enabled='true'/>
   </Course>
  </Routing>
</Profile>

If you do not want to start the route at your current local time, provide the start time of the route as RoutingParameter.

"options": [
  {
    "parameter": "START_TIME",
    "value": "2014-10-17T08:00:00+02:00"
  }
]

Time zone information can be displayed in two different ways at each route segment: as UTC offset in minutes or as detailed and time-independent string in gdf time domain format.

Time zone information as UTC offset

The current UTC offset along a route is displayed at each waypoint by default. To enable UTC offset information at each segment set the ResultListOptions parameters segments and utcOffsets to true.

"details": {
  "segments": true,
  "utcOffsets": true
}

After sending the request, the UTC offset in minutes is displayed in the route response at each WayPoint and - if enabled in the request - at each RouteListSegment.

"segments": [
  {
    ...
    "utcOffset": 60,
    ...
  },
  ...
],
"stations": [
  {
    ...
    "wayPointType": "START",
    "utcOffset": 60
  },
  ...
]

Time zone information as gdf time domain strings

Some content of a feature layer theme can be displayed as feature description string at each route segment. Read the technical concept About FeatureLayer for more information about the general mechanism.

In order to retrieve feature description strings in the result list, the ResultListOptions parameters segments and featureDescriptions have to be set to true in the request.

"details": {
  "segments": true,
  "featureDescriptions": true
}

After sending the request, the FeatureDescription element holds time zone information in gdf time domain format.

"segments": [
  {
    ...
    "featureDescriptions": [
      {
        "themeId": "PTV_TimeZones",
        "timeDomain": "[[(M1d1){y1}]-[[(M3l11){d217}]*[(M10l11){-d217}]]]",
        "description": "timeZoneId=0|offsetFromUTC=60|daylightSavingTime=0|hasDaylightSavingTime=1"
      },
      {
        "themeId": "PTV_TimeZones",
        "timeDomain": "[[(M3l11){d217}]*[(M10l11){-d217}]]",
        "description": "timeZoneId=0|offsetFromUTC=60|daylightSavingTime=60|hasDaylightSavingTime=1"
      }
    ],
    ...
  },
  ...
]

How to Use Feature Layer TimeZones

Related Topics

Terminology

Benefits

Prerequisites

Concept

Installation Guide

Programming Guide

Time zone information as UTC offset

Time zone information as gdf time domain strings