Toll: Difference between revisions Discussion View history

(→‎Prices: added some more toll price info)
(a lot more stuff in the FAQ and entry/exit sections)
Line 43: Line 43:
-->
-->
== Prices ==
== Prices ==
In 2019 Waze unveiled the capability to store and display prices for toll roads. Toll price information is contained in JSON files, which are created in a [http://tolls.waze.com special tool] outside of the [[Waze Map Editor|Waze Map Editor.]] This toll tool also contains documentation and a playground for the testing of price files before submission for use in the app. Since a lot of documentation about toll prices is already available in the tool, this section will provide a brief overview of the process, along with answers to any frequently-asked questions that editors may have about the feature.
In 2019 Waze unveiled the capability to store and display prices for toll roads. Toll price information is contained in ''price files'', which are collections of data in the JSON format that associate segments and nodes from WME with prices. Price files are created in a [http://tolls.waze.com special toll tool] outside of the [[Waze Map Editor|Waze Map Editor.]] This toll tool also contains documentation and a playground for the testing of price files before submission for use in the app. Since a lot of documentation about toll prices is already available in the tool, this section will provide a brief overview of the process, along with answers to any frequently-asked questions that editors may have about the feature.


=== Overview ===
=== Overview ===
Each file contains one or more tolls, and each toll contains one or more sections, along with currency, toll type (static or dynamic), rules (pay-per-section-count, entry/exit price and pay-per-section) and other info. Price information can be in different places depending on the rule of the toll. Each section contains one or more segments, and each segment is listed with a segment ID and two node IDs: the fromNode and the toNode. When the routing server calculates a route that passes in order immediately through the FromNode ID, the segment ID and the ToNode ID of a segment stored in a price file, it looks up and attempts to display a price. If any of these IDs or their order are changed through cutting, merging, disconnection or deletion, the toll price file will not work until it can be updated with new IDs and re-uploaded onto the server. {{As of|August 2019}} the editor gives no indication that segments have any associated pricing information, and the toll tool gives no indication that a file contains broken segments, apart from manually testing routes through specific segments. Therefore, '''editors must be very careful not to inadvertently break price files when working with tolls'''. While building price files, some editors have added map comments or higher locks on segments that they use, in order to provide some level of protection, but this has not been done universally. Each section can also be associated with a venue ID of a toll booth or other place. {{As of|August 2019}} the venue ID is not used in the app, and only static pricing is supported. The segment, node and venue IDs are the only common elements between the toll price tool and WME.
Each file contains one or more tolls, and each toll contains one or more sections, along with currency, toll type (static or dynamic), rules (pay-per-section-count, entry/exit price and pay-per-section) and other info. Prices can be in different places depending on the rule of the toll. Multiple prices can be entered for drivers holding different passes, driving different vehicle types or driving at different times or days. The lowest applicable price is shown to the user, although if a pass can allow someone to pay a lower price, the app may suggest adding the pass in the app. Each section contains one or more segments, and each segment is listed with a segment ID and two node IDs: the fromNode and the toNode. When the routing server calculates a route that passes in order immediately through the FromNode ID, the segment ID and the ToNode ID of a segment stored in a price file, it looks up and attempts to display a price.
 
If any of these IDs or their order are changed through cutting, merging, disconnection or deletion, the toll price file will not work.  It must be updated with new IDs and re-uploaded onto the server. {{As of|August 2019}} the editor gives no indication that segments have any associated pricing information, and the toll tool gives no indication that a file contains broken segments, apart from manually testing routes through specific segments. Therefore, '''editors must be very careful not to inadvertently break price files when working with tolls'''. While building price files, some editors have added map comments or higher locks on segments that they use, in order to provide some level of protection, but this has not been done universally. Each section can also be associated with a venue ID of a toll booth or other place. {{As of|August 2019}} the venue ID is not used in the app, and only static pricing is supported. The segment, node and venue IDs are the only common elements between the toll price tool and WME.


==== Pay-per-section ====
==== Pay-per-section ====
This is the most common rule used for toll roads. It is also called open tolling, in that traffic can come from anywhere and pay the same price.
This is the most common rule used for toll roads. Drivers pay fixed amounts at each collection point along a toll road. The amounts collected do not depend on how far the driver has driven on the road. In the toll tool, the pay-per-section rule is used, sections are defined for every toll collection area, whether a mainline toll plaza or a pair of exit and entrance ramps. Prices are added to each section. Multiple prices can be added per section, depending on passes, vehicle types, and valid times, days or dates. If one section has a pass-specific price, all sections must have this price added in. So, for example, if a road collects tolls through both cash and E-ZPass transponders, a section that contains E-ZPass-only segments must have a cash price (nothing in the permit field) defined, along with an E-ZPass price (ezpass-us or a variant in the permit field), even if only E-ZPass holders will be routed through it.


==== Entry/exit price ====
==== Entry/exit price ====
When traffic is charged different amounts at an exit depending on where they entered, toll prices must use this rule. It is also called closed tolling, in that traffic is recorded entering a closed system at a defined point, then pays a certain amount when they exit the system that is based upon the points of entry and exit.
When traffic is charged different amounts at an exit depending on where they entered, toll prices must use this rule. Prices should not be entered in the sections, and if they are, they will not be used. Instead, prices must be entered using one of two ways, entry/exit matrices or entry/exit rules. In the early versions of the toll tool, only entry/exit rules were available. An entry section and exit section, and optionally an intermediate section, are filled in for each price in the system. The number of rules increases quadratically with the number of sections (entrances and exits, and this becomes cumbersome very quickly. Some files have become so large that they have caused browsers to crash.
 
More recently the entry/exit matrix was developed. Instead of making a new line for each individual entry/exit price, a square matrix is generated based on the number and order of sections in the file. Note that the sections listed above the matrix in the tool are the "from" sections, the sections listed to the left of the matrix are the "to" sections, and the rows of prices in the JSON data are transposed as columns in the tool. So if a file has 20 entries and 20 exits defined individually, a 40x40 matrix is generated, with 1600 individual prices. If the entry sections are listed sequentially before the exit sections in the file, this would mean that the lower left quadrant of the matrix (as displayed in the tool) is where the prices should go, because this represents the prices from the entry sections to the exit sections. Multiple price matrices can be added to a toll, dependent upon which permit, time or vehicle type they apply to.


=== FAQ ===
=== FAQ ===


==== Why is there limited access to the toll tool? ====
==== Why is there limited access to the toll tool? ====
The toll tool is complex, and it takes a while to learn how to use. It was first presented at the NA Mega Meetup in February 2019, and a significant portion of the conference time was dedicated to learning how to use it. Originally only attendees of this meetup had access, but as the months rolled on, the documentation and best practices became clearer, and more editors were given access.
==== How do I get access? ====
If you would like to add toll prices, speak with your [[Regional Coordinator|regional coordinator]]. Anyone who has access can request it for others, but as with many community issues, it's best to have coordination by a coordinator.


==== Can the toll tool handle prices for different vehicle types, passes and times? ====
==== Can the toll tool handle prices for different vehicle types, passes and times? ====
Yes, prices can be defined by vehicle type, toll/HOV pass, hours and minutes of the day, days of the week and dates in the year.


==== What do I do if I see a UR about a toll price problem? ====
==== What do I do if I see a UR about a toll price problem? ====
First, try to gather info from a reporter. If they don't have the correct pass or vehicle type set in the app, they could be getting an incorrect price. If they recalculated their route while on a toll road, that may cause the price display to fail (especially if the pricing is entry/exit). Also reach out to an SM or someone you know with access to the toll tool. They will be able to find who built the price file in question, if it exists. '''Price files can only be edited by the user who created them.''' Therefore the builder of the price file should be the one to fix it. If this person is not available, someone else can create a correct file under a new name and request that their file replace the incorrect file during the next upload process.
==== How does uploading work? ====
When a file is ready to be used in the app, its builder can request an upload through a form linked under the Welcome tab of the toll tool. Staff generally uploads new files and corrections every two weeks, after checking for problems with the files and conflicts between different files over the same segment and direction. If someone has saved a public file for the same toll road that you are working on, try to coordinate with them, and check the list of uploaded files to make sure that uploading your work won't create a conflict. The mere existence of multiple public files for the same road that ''have not'' been uploaded is not a problem; sometimes people collaborate and copy work from one person's file to their own.
==== Can the toll tool handle prices with multiple currencies? ====
At this point, each toll file must use one currency, so uploading a toll price in multiple currencies would require multiple files. However, the existence of multiple files for the same segment and direction creates a conflict, so multi-currency prices have not been seen to work successfully.
==== How do I log into the tool? ====
The default username is the email address used when requesting access to the tool, and the default password is the Waze username. This password can by changed under the My Information tab.
==== How should I split up files and tolls for a given area or road? ====
Toll price files are intended to represent all tolls within a given area or system, such as New York City or the Pennsylvania Turnpike system. It is not necessary to split files by direction or route number. It is also not necessary to split tolls by direction, unless perhaps one is using entry/exit rules (not matrices), which can make a toll very large. In most cases, both directions of a toll road can be listed in the same toll, with each section including segments in both directions. This is because, at least with pay-per-section and entry/exit matrix tolls, one toll containing both directions is only slightly larger than one toll containing a single direction. It is much smaller and easier to build than two tolls that each contain one direction. In the early versions of the toll tool, guidance was different, and its capabilities have improved.
It ''is'' necessary to split tolls by pricing rules. If a part of a toll road uses a pay-per-section system, and another part uses an entry/exit system, multiple tolls must be made for the different systems.
==== Do I need to fill in every field? ====
Under tolls, the toll_id, road_local_name and currency fields must be filled in, and one rule must be chosen (if more than one is chosen, only one will work). At least one section must be added. Under sections, the section_id, road_local_name, section_local_name and location must be filled in. At least one segment must be added. Under segments, the id, fromNode and toNode fields must be filled in, but the tool can extract these from segments marked with toll, by filled in the permalink field and clicking Populate (if the segment from the Permalink does not have a toll flag or toll free restriction in the most recent tile build, the tool will only extract the segment ID). The polyline field only provides a visual indicator of the toll road in the playground; this can be left blank if not planning to test the file in the playground. The venue_id field is not currently used and can also be left blank, but it's good to fill in if a Waze place exists for the toll booth in the section.
==== What do I put for the section/road_local_name and section_id fields? ====
Whatever you want. These fields must be filled in but are only for internal references within the file; they are not displayed in the app. For section names and IDs, It's generally helpful to have something that is short and descriptive, which corresponds to how the toll plazas or sections are publicly described by the toll authority, in order to quickly identify sections within a file when adding prices. Section ids must be unique for each section.
==== What happens if I don't select any vehicle types or days of the week? ====
The price applies to all vehicle types or on all days of the week. There's no need to select everything, and in the case of vehicle types, this would exclude any new vehicle types that are not included in the tool but may be enabled in the app in the future.
==== How do I handle time-based or date-based prices? ====
There must be a default price that is valid for a whole day of the week and/or dates, and it must be listed first. It doesn't matter whether the default price is higher or lower than the time-based price. So for example, if a toll price is scheduled to increase on January 1, 2020
==== Is there an easier way to do this? ====
The Portuguese community have developed another tool in Google Sheets that automates some of the price file generation process.

Revision as of 19:49, 27 August 2019

Do not cut, merge or disconnect any segment of a toll road, whether it is marked or not, without consulting a state manager in your state, preferably someone with access to the toll tool. Doing so may break a toll price file. See the prices section for further details.

Waze has the ability to mark toll facilities, in order to provide better routing, pricing and other information to users. In addition to traditional toll roads, facilities that may be marked as toll include HOT lanes, toll ferries and roads through parks that require an entrance fee. Depending on the facility, this can be done by simply marking a whole segment as a toll road, or by creating a toll-free partial restriction. For either method used, the effects are identical when a user's route traverses a qualifying toll road segment. Routes that traverse a toll segment will show a toll icon on the route preview and route comparison screens in the app. An estimated price will be displayed in the toll icon, if this information has been added to Waze's toll price tool. Toll roads also affect routing in unique ways.

Routing

Toll roads have two different routing effects, dependent upon what a user selects in the navigation settings in the client app:

  1. When the client option to "avoid toll roads" is disabled, a small routing penalty is added to every transition from a toll segment to a non-toll segment.
    • This means that the routing server may choose a free route, even if it takes a little longer than a toll route.
    • This also means that the routing server may choose a route with one toll segment, even if it takes a little longer than a route with multiple discontinuous toll segments.
  2. When the client option to "avoid toll roads" is enabled, a large routing penalty is added to the route for every single toll segment, even in sequence.
    • This means that any toll segment will be avoided if at all reasonably possible.
    • This also means that given two route options the routing server will choose the one with the fewest number of toll segments, regardless of if they are consecutive or not.

Note: The penalty for "avoid toll roads" is very high, and the definition here of reasonable may seem extreme. The routing server will prefer a significant detour to avoid a toll, but not one it considers to be insane or impossible. The exact amounts of both penalties are proprietary information and are not published by Waze.

Editing

For most toll roads, all traffic must pay a toll at all times. We will call this a fully tolled road. If a road can be used for free by a subset of vehicles or at certain times, we will call it a partially tolled road.

Fully tolled

To represent a fully tolled road in the editor, click the Add restrictions button and check the Toll road attribute.

The choice of which segments to mark as toll can be made according to one of two methods. Note that within a certain area, these methods should not be mixed, because improper routing may result.

Only collection points

Under this method, only a segment (entrance/exit/highway) that actually traverses through a toll booth, collection point, or ticket dispenser is marked as toll. This means that all paths traverse a single toll segment per toll location, and they are only assessed with a single toll penalty, whether avoid toll roads is on or off. This may mean that only a single segment is tolled, or if there are parallel segments going through the toll location (e.g. multiple entrance or exit ramps, cash and pass lanes), a single segment of each path is tolled. This method works well when a driver wants to or must use a toll road, and the avoid toll roads option is enabled. This is the preferred method for most of the US.

There are a few benefits to this method, as opposed to marking every segment of a toll road.

  • It allows the routing server to pick a route with lowest number of tolls along the route.
  • It will apply an identical penalty to two different toll roads (assuming they both have one toll collection point) regardless of how many segments the toll road is made of. This allows two toll bridges and/or tunnels to the same destination to be treated equally; the routing server will pick the most appropriate one regardless of their individual segment count, and the .
  • It reduces the likelihood of detours through rest areas, whose roads would not otherwise be tolled.

All segments

In some regions editors may choose to mark all segments of a toll road as toll. This works well for users who do not have the avoid toll roads option enabled, and multiple options exist with toll collection points spaced closely together. The routing server assesses the same penalty for traveling on any toll road in the area, because one transition off of a toll road exists for any option, and the user can decide on whichever price they are willing to pay. If this method is used, it's best to mark ramps between toll facilities as toll roads also, so that an extra transition penalty isn't applied for users who aren't looking to avoid tolls.

Partially tolled

Partially tolled roads are represented in the editor with toll free restrictions. For example, if a road collects a toll from all vehicles except for electric vehicles, a toll-free restriction may be added to specify that electric vehicles are toll-free. If the electric vehicle type is selected in the client, this road will treated like any other free road. If any other vehicle type is selected in the app, this road will be treated like any other toll road. The partial restrictions page explains in great detail how to add these restrictions.

Prices

In 2019 Waze unveiled the capability to store and display prices for toll roads. Toll price information is contained in price files, which are collections of data in the JSON format that associate segments and nodes from WME with prices. Price files are created in a special toll tool outside of the Waze Map Editor. This toll tool also contains documentation and a playground for the testing of price files before submission for use in the app. Since a lot of documentation about toll prices is already available in the tool, this section will provide a brief overview of the process, along with answers to any frequently-asked questions that editors may have about the feature.

Overview

Each file contains one or more tolls, and each toll contains one or more sections, along with currency, toll type (static or dynamic), rules (pay-per-section-count, entry/exit price and pay-per-section) and other info. Prices can be in different places depending on the rule of the toll. Multiple prices can be entered for drivers holding different passes, driving different vehicle types or driving at different times or days. The lowest applicable price is shown to the user, although if a pass can allow someone to pay a lower price, the app may suggest adding the pass in the app. Each section contains one or more segments, and each segment is listed with a segment ID and two node IDs: the fromNode and the toNode. When the routing server calculates a route that passes in order immediately through the FromNode ID, the segment ID and the ToNode ID of a segment stored in a price file, it looks up and attempts to display a price.

If any of these IDs or their order are changed through cutting, merging, disconnection or deletion, the toll price file will not work. It must be updated with new IDs and re-uploaded onto the server. As of August 2019 the editor gives no indication that segments have any associated pricing information, and the toll tool gives no indication that a file contains broken segments, apart from manually testing routes through specific segments. Therefore, editors must be very careful not to inadvertently break price files when working with tolls. While building price files, some editors have added map comments or higher locks on segments that they use, in order to provide some level of protection, but this has not been done universally. Each section can also be associated with a venue ID of a toll booth or other place. As of August 2019 the venue ID is not used in the app, and only static pricing is supported. The segment, node and venue IDs are the only common elements between the toll price tool and WME.

Pay-per-section

This is the most common rule used for toll roads. Drivers pay fixed amounts at each collection point along a toll road. The amounts collected do not depend on how far the driver has driven on the road. In the toll tool, the pay-per-section rule is used, sections are defined for every toll collection area, whether a mainline toll plaza or a pair of exit and entrance ramps. Prices are added to each section. Multiple prices can be added per section, depending on passes, vehicle types, and valid times, days or dates. If one section has a pass-specific price, all sections must have this price added in. So, for example, if a road collects tolls through both cash and E-ZPass transponders, a section that contains E-ZPass-only segments must have a cash price (nothing in the permit field) defined, along with an E-ZPass price (ezpass-us or a variant in the permit field), even if only E-ZPass holders will be routed through it.

Entry/exit price

When traffic is charged different amounts at an exit depending on where they entered, toll prices must use this rule. Prices should not be entered in the sections, and if they are, they will not be used. Instead, prices must be entered using one of two ways, entry/exit matrices or entry/exit rules. In the early versions of the toll tool, only entry/exit rules were available. An entry section and exit section, and optionally an intermediate section, are filled in for each price in the system. The number of rules increases quadratically with the number of sections (entrances and exits, and this becomes cumbersome very quickly. Some files have become so large that they have caused browsers to crash.

More recently the entry/exit matrix was developed. Instead of making a new line for each individual entry/exit price, a square matrix is generated based on the number and order of sections in the file. Note that the sections listed above the matrix in the tool are the "from" sections, the sections listed to the left of the matrix are the "to" sections, and the rows of prices in the JSON data are transposed as columns in the tool. So if a file has 20 entries and 20 exits defined individually, a 40x40 matrix is generated, with 1600 individual prices. If the entry sections are listed sequentially before the exit sections in the file, this would mean that the lower left quadrant of the matrix (as displayed in the tool) is where the prices should go, because this represents the prices from the entry sections to the exit sections. Multiple price matrices can be added to a toll, dependent upon which permit, time or vehicle type they apply to.

FAQ

Why is there limited access to the toll tool?

The toll tool is complex, and it takes a while to learn how to use. It was first presented at the NA Mega Meetup in February 2019, and a significant portion of the conference time was dedicated to learning how to use it. Originally only attendees of this meetup had access, but as the months rolled on, the documentation and best practices became clearer, and more editors were given access.

How do I get access?

If you would like to add toll prices, speak with your regional coordinator. Anyone who has access can request it for others, but as with many community issues, it's best to have coordination by a coordinator.

Can the toll tool handle prices for different vehicle types, passes and times?

Yes, prices can be defined by vehicle type, toll/HOV pass, hours and minutes of the day, days of the week and dates in the year.

What do I do if I see a UR about a toll price problem?

First, try to gather info from a reporter. If they don't have the correct pass or vehicle type set in the app, they could be getting an incorrect price. If they recalculated their route while on a toll road, that may cause the price display to fail (especially if the pricing is entry/exit). Also reach out to an SM or someone you know with access to the toll tool. They will be able to find who built the price file in question, if it exists. Price files can only be edited by the user who created them. Therefore the builder of the price file should be the one to fix it. If this person is not available, someone else can create a correct file under a new name and request that their file replace the incorrect file during the next upload process.

How does uploading work?

When a file is ready to be used in the app, its builder can request an upload through a form linked under the Welcome tab of the toll tool. Staff generally uploads new files and corrections every two weeks, after checking for problems with the files and conflicts between different files over the same segment and direction. If someone has saved a public file for the same toll road that you are working on, try to coordinate with them, and check the list of uploaded files to make sure that uploading your work won't create a conflict. The mere existence of multiple public files for the same road that have not been uploaded is not a problem; sometimes people collaborate and copy work from one person's file to their own.

Can the toll tool handle prices with multiple currencies?

At this point, each toll file must use one currency, so uploading a toll price in multiple currencies would require multiple files. However, the existence of multiple files for the same segment and direction creates a conflict, so multi-currency prices have not been seen to work successfully.

How do I log into the tool?

The default username is the email address used when requesting access to the tool, and the default password is the Waze username. This password can by changed under the My Information tab.

How should I split up files and tolls for a given area or road?

Toll price files are intended to represent all tolls within a given area or system, such as New York City or the Pennsylvania Turnpike system. It is not necessary to split files by direction or route number. It is also not necessary to split tolls by direction, unless perhaps one is using entry/exit rules (not matrices), which can make a toll very large. In most cases, both directions of a toll road can be listed in the same toll, with each section including segments in both directions. This is because, at least with pay-per-section and entry/exit matrix tolls, one toll containing both directions is only slightly larger than one toll containing a single direction. It is much smaller and easier to build than two tolls that each contain one direction. In the early versions of the toll tool, guidance was different, and its capabilities have improved.

It is necessary to split tolls by pricing rules. If a part of a toll road uses a pay-per-section system, and another part uses an entry/exit system, multiple tolls must be made for the different systems.

Do I need to fill in every field?

Under tolls, the toll_id, road_local_name and currency fields must be filled in, and one rule must be chosen (if more than one is chosen, only one will work). At least one section must be added. Under sections, the section_id, road_local_name, section_local_name and location must be filled in. At least one segment must be added. Under segments, the id, fromNode and toNode fields must be filled in, but the tool can extract these from segments marked with toll, by filled in the permalink field and clicking Populate (if the segment from the Permalink does not have a toll flag or toll free restriction in the most recent tile build, the tool will only extract the segment ID). The polyline field only provides a visual indicator of the toll road in the playground; this can be left blank if not planning to test the file in the playground. The venue_id field is not currently used and can also be left blank, but it's good to fill in if a Waze place exists for the toll booth in the section.

What do I put for the section/road_local_name and section_id fields?

Whatever you want. These fields must be filled in but are only for internal references within the file; they are not displayed in the app. For section names and IDs, It's generally helpful to have something that is short and descriptive, which corresponds to how the toll plazas or sections are publicly described by the toll authority, in order to quickly identify sections within a file when adding prices. Section ids must be unique for each section.

What happens if I don't select any vehicle types or days of the week?

The price applies to all vehicle types or on all days of the week. There's no need to select everything, and in the case of vehicle types, this would exclude any new vehicle types that are not included in the tool but may be enabled in the app in the future.

How do I handle time-based or date-based prices?

There must be a default price that is valid for a whole day of the week and/or dates, and it must be listed first. It doesn't matter whether the default price is higher or lower than the time-based price. So for example, if a toll price is scheduled to increase on January 1, 2020

Is there an easier way to do this?

The Portuguese community have developed another tool in Google Sheets that automates some of the price file generation process.