Date and Time

To obtain the best results date and time will be considered for calculating the route, the travel time and toll.

Route Calculation

Many roads cannot be used by trucks at any time. The Routing API will automatically consider roads prohibited for the selected vehicle and the selected date and time to find the best allowed route.

Driving Time Calculation

To calculate the driving time an average speed for every single road is taken into account. For more accurate results the average and the live traffic situation will be considered.

The average traffic situation means that for each road the average speed at that day of the week and that time of day will be considered. The rush hours in the mornings and evenings with lower average speeds will be considered that way.

The live traffic situation comprises traffic jams, road works and other disturbances which usually have a short validity of only a few hours. Route calculations in the future will not be affected by them apart from long-term blockings because of road works.

Toll Calculation

In many countries toll prices depend on when the toll roads, in particular bridges, tunnels or mountain passes, are passed. The Routing API will calculate the correct price depending on the date and time of the route.

Usually, the data contains the currently valid tariffs. Sometimes, price changes may be known months in advance or there are drafts for potential price changes. In such cases the parameter options[tollTime] can be used with a corresponding date in the future to retrieve the upcoming prices for your route. See also the concept on toll for more information.

Specifying Date and Time

When the route will be started now, it is not necessary to specify date and time, the current date and time will be used automatically. When the route will take place at a different date and time, specify either options[startTime] or options[arrivalTime] in a format according to RFC 3339. When both are specified, an error will be returned.

https://api.myptv.com/routing/v1/routes?waypoints=49.6008648,6.0670280&waypoints=49.4404499,6.4970397&options[startTime]=2020-12-24T12:00:00%2B01:00

It is not necessary to specify an offset to Coordinated Universal Time (UTC) as in the example above, instead the time is treated as local time at start (when options[startTime] is specified) or destination (when options[arrivalTime] is specified) and the offset to UTC is determined automatically.

Note that options[arrivalTime] cannot be specified when requesting the results SCHEDULE_REPORT and SCHEDULE_EVENT nor when openingIntervals, serviceTime or workingHoursPreset are specified.

All times present in the response will have the offset to UTC which is specified or determined from the request.

GDF Time Domains

GDF time domains are a possibility to specify time intervals. Their advantage is that multiple recurring intervals can be defined by only one string. For a complete definition of the GDF time domain format please have a look at the ISO format specification. Hereafter, only the features supported by PTV Developer will be described.

When do I need time domains?

Currently, time domains are not used in the requests. For instance to specify operating intervals at customers, simple intervals that consist of a start date and and end date are usually enough. On the other hand there may be driving restrictions that recur every workday or only on weekends. Time domains are designed to specify such restrictions efficiently. Time domains are returned in the violation events when a restriction is not permanent, but only valid at certain times. Then, the time domain specifies when this restriction is valid.

How do time domains work?

The time domain for the restriction for trucks above 18 tons in the image above looks like this:

[[(t1){d1}]+[[(t2){d6}]*[(h0){h7}]]+[[(t2){d5}]*[(h21){h3}]]+[[(t7){d1}]*[(h13){h11}]]]

That looks complicated, so let's have a look at the syntax and structure first:

Generally, a time domain is composed of a starting date and/or a time duration with the following notation: [(Starting Date){Time duration}]. '[' and ']' are mandatory and exactly one of each shall be used to encase a basic time domain.

The following terms can be used to describe the desired time domain. Each of those terms is valid in the starting date block. Terms marked in the column "Can be used as duration" are also valid as time duration. In the case of acting as a time duration, all terms have possible values in the range 0...99.

Notice that the time terms, for the starting date and for the duration, must be added following the logical sequence.

Starting date combination sequence:

Duration combination sequence:

There are some important details when specifying "days":

• The week starts on a Sunday, hence 1 means Sunday, 2 means Monday and 7 means Saturday.
• The value 8 stands for public holiday.
• To specify a weekday in a specific week of a month, the letter "f" can be used: {f23} refers to the second Tuesday in a month, because the first number represents the week of the month and the second number represents the weekday as described above.
• There is not always, for example, a fifth Tuesday in a month, so to specify the last Tuesday in month the letter "l" can be used as follows: {l13}. The first letter specifies the occurrence in the month when counting from the end of the month to the beginning.
• Furthermore the days of the week are the only term that can be used recursive in the starting date block, see for example: [(t2t3t4h8){h10}] represents intervals from 8am to 6pm on Mondays, Tuesdays and Wednesdays.

It is also possible to combine multiple GDF time domains. There are three basic possibilities to do that:

• Union of sets via the operator +
• Intersection of sets via the operator *
• Subtraction of sets via the operator -

With that information we can decipher the time domain above and see that it matches the information on the street sign:

• [(t1){d1}]]: Starts on day 1 of the week, so this means Sunday and is valid for one day. So the restriction is valid every Sunday.
• [[(t2){d6}]*[(h0){h7}]]: The first part represents the time from Monday to Saturday. The second part represents the time from midnight to 7 AM. As they are combined by intersection, this means Monday to Saturday from midnight to 7 AM.
• [[(t2){d5}]*[(h21){h3}]]: The first part represents the time from Monday to Friday. The second part represents the time from 9 PM to midnight.
• [[[(t7){d1}]*[(h13){h11}]]: The first part represents Saturday. The second part represents the time from 1 PM to midnight.

A few more examples:

• [[(h9){h3}] + [(h13){h4m30}]] represents intervals from 9am to 12am and from 1pm to 5:30pm every day
• [[[(h9){h3}] + [(h13){h4m30}]] * [(t2){d5}]] restricts the above intervals to the weekdays Monday until Friday
• [[[[(h9){h3}] + [(h13){h4m30}]] * [(t2){d5}]] - [(M12d24){d1}]] excludes the 24th of December from the above intervals