Travel Mapping

Tracking Cumulative Travels

Travel Mapping Manual: How to participate in the project


🔗 How to create a user list file

The basic idea is to make a list of highway sections you have traveled and collect them into a plain text file to be submitted to Travel Mapping. The text file will be processed to populate a set of custom stats pages and maps describing your travels.

For examples, you can browse the travel summaries of any of our users.

🔗 Travel Mapping data basics

All routes mappable by Travel Mapping can be found organized by highway system in the Highway Browser and are listed in the Route Finder. Selecting a route through the Highway Browser or Route Finder brings up that route in the showroute tool. You can also get to showroute for any route by clicking on a segment on any Mapview map, then clicking on the route name in the popup that appears.

To keep the size of the project's data manageable, routes are approximated by waypoints located at interchanges, major intersections, and borders. showroute provides a list of waypoints that you use specify the start and end points of each segments of the route that you have traveled. By default, showroute shows a route within a single region (e.g., state, province). Routes that span multiple regions (like U.S. Interstate highways), the entire route can be viewed by clicking on the "View Connected Route" link under the highway shield in the upper left of the showroute window. You will learn below how to create entries in either case.

showroute gives all of the information you need to create the entries for your user list file that will represent your traveled segments: ".list Name" for the route, and the labels of the waypoints at the ends of your traveled segments. For routes within a region, you will find the .list Name under the shield in the upper left, and waypoint labels can be found in the table on the left side of the window or by clicking any of the waypoints on the map. When viewing a connected route, the .list Name is in the waypoint table above the points in each region, and the waypoint labels are in the table and again can be found by clicking on waypoints on the map.

🔗 First steps with email submission

  1. 🔗 Choose an alphanumeric username.

    Use only English letters (A-Z or a-z), numbers (0-9), and underscores (_) in your username, and keep the name at or under 48 characters long. Avoid characters with diacritical marks, and characters from other alphabets; otherwise your file will not be processed.

  2. 🔗 Create a plain text file.

    Name the file username.list, replacing username with the username you chose. For example, if you choose the name highwayguy, name your file highwayguy.list .

  3. 🔗 Make a list of highway sections you have traveled.

    Break up your travels into the traveled sections on each route. For each route section, add one line to your .list file with the single-region format:

    Region Route Waypoint1 Waypoint2

    or the multi-region format (which can be used any time but is most useful for multi-region connected routes):

    Region1 Route1 Waypoint1 Region2 Route2 Waypoint2

    For example, if you traveled in the United States on Interstate 70 between Exit 52 in Illinois and Exit 249 in Missouri, you could specify that with two single-region lines:

    IL I-70 52 MO/IL
    MO I-70 MO/IL 249

    or with a single mutli-region line:

    IL I-70 52 MO I-70 249

    All of the information can be gathered from the showroute page for the route. However, the easiest and least error-prone way to generate your .list file entries is to use showroute's .list Tool. You can enable this on any showroute page by enabling the checkbox next to ".list Tool" at the top of the window.

    This brings up the ".list Toolbox" at the upper right. As segments of the route are selected or unselected, the entry or entries that would need to be added to your .list file will appear and those segments are highlighted on the map. Segment selections can be manipulated in a few ways:

    • Click on any segment on the map to toggle whether it is selected or not.
    • Click on a segment then hold the SHIFT key while clicking on another segment selects/unselects those segments and all in between.
    • The "Clear Selection" button unselects all segments and the "Select All Segments" button selects them all.
    • If you already have any segments mapped for the route in Travel Mapping from a previous .list file submission, the "Select Clinched Segments" button will select them.

    Once you have the segments that represent your travels selected, you can copy the text from the .list Toolbox into your .list file. The "Copy to Clipboard" button copies all of the text to your system's clipboard for easy pasting into your .list file.

    Continue adding entries for routes to complete your travels. See below if you need more examples on how to break down your travels into "sections" to enter into the file.

    Note that a mechanism is in place to automatically include concurrent highways and credits you for all of them as long as the segment is included in at least one of them.

    We recommend starting with a small number of routes and submitting an initial draft to be included in the site update to make sure that you understood the procedure well.

  4. 🔗 Check your work.

    Make sure the following items are correct:

    • Each line has exactly the four or six required fields: Region Route Waypoint1 Waypoint2 or Region1 Route1 Waypoint1 Region2 Route2 Waypoint2
    • The fields have only spaces or tabs between them. Other delimiters may prevent the site update program from parsing your file correctly.
    • The file is saved as plain text with a .list extension. Word processor files (Microsoft Word, Open Office Write, etc.) and rich-text formats will not work. If you use a word processor to create your file, be sure to select "Save As..." and save the file in a plain text format.

  5. 🔗 Send your .list file as an email attachment to

    Mention in the subject line that your username is a new one. You're set -- just wait for the next site update after which you will see your maps and stats live on the site. Site updates typically occur nightly between 9 and 11 PM US/Eastern.

  6. 🔗 After the next site update, look for your name on the Traveler List.

    Once your file has been processed, your name will appear in this list along with all the other travelers. Click on your username and enjoy your traveled highway stats and maps.
    Additional stats are available in csv files linked from

  7. 🔗 Check the user log file.

    Check your online log file (also directly linked on your user stats page). If you included a highway or point label that the mapping script does not recognize, it will tell you in the first segment of your log file. Sometimes highway data is updated, and this may generate a new error. You can find a note in the first lines of your log file. Check the updates page for info on what has been changed to the route.

    Route updates that don't break your .list file are also reported in your log file. Notes to changes since the last update of your .list file are found at the beginning, older changes at the very end of the log file. You should also check the updates page frequently to find added routes or highway systems. Changes to systems in preview state are not notified.

  8. 🔗 Update your file as needed by emailing an updated copy.

    If you do more traveling, you can update your .list file to reflect the new highways on which you have traveled. To submit your updated file, just email it again, and it will be processed in the subsequent site update. Feel free to update as often as you wish!
Travel Mapping's volunteers hope that you enjoy your maps and stats pages from this free service!

🔗 Solutions to common problems

  1. 🔗 An invalid username was chosen.

    Only the characters A-Z, a-z, 0-9, and the underscore _ are allowed in usernames. If you used other characters, such as non-English characters or symbols, remove them.

  2. 🔗 The filename does not match the username.

    If the username is highwayguy80, then the filename should be highwayguy80.list, not highwayguy80.txt, HighwayGuy80.list, arkansas.list, motorways.list, etc.

    Note that since modern desktop operating systems hide the file extension .list by default and/or include an extra, hidden .txt extension, files with a .list.txt extension are also accepted (e.g., highwayguy80.list.txt) and do not cause any problems for the site update process.

  3. 🔗 The file was not emailed.

    Check that you attached your file to your email and that you finished sending it. Obviously files that are not received cannot be processed!

  4. 🔗 The file was sent but has not yet been processed.

    Site updates typically occur daily, and the time of the last update (currently 2024-06-29 22:51:28 US/Eastern) can always be found at the bottom of the project's home page. Expected disruptions in the site update schedule will be mentioned in the project forum. If your file was sent more than about 30 minutes before the most recent update and you don't see your changes reflected on the site, you can check on its status with an additional email or simply resend.

  5. 🔗 The new file was processed, but all the highways from the previous file are no longer shown.

    Each new file you submit should contain all your traveled highways, not just additions to those from a previously submitted file. The new file always replaces the previous file rather than supplementing it. This allows users to not only add or modify lines in their file but also to delete them as needed.

🔗 More examples of how to break down your travels

Below are several example entries for a user's .list file.

🔗 Advanced features

🔗 Specifiying unranked users and additional traveler info

In the UserData repository, a csv file listfileinfo.csv is maintained where additional information can be specified. Lines in the file have three semicolon-separated fields:
The listname is the TM username, description is a brief description of the meaning of the file (e.g., your actual name, or what subset of your travels the file contains, etc.), and includeInRanks is 1 for normal users and 0 for users that should be excluded from rankings on the site because it does not represent the actual lifetime travels of an individual. All list files that do not represent actual lifetime travels of an individual should be given an entry. An entry to specify a description can optionally be added for any user. These can be added by email request to or by submitting a pull request in the repository.

🔗 How to become a highway data manager

Some experienced users volunteer to help the project. If this interests you, start by reporting problems with existing highway data. Those who have learned the project's structure and highway data rules and guidelines can help greatly by providing review of new highway systems in development. Highly experienced users can learn how to plot new highway systems under the guidance of experienced contributors.
The steps to become a highway data manager are as follows:
  1. 🔗 Become an active user and get familiar with the project structure. Create a list files and understand how routes are organized into highway systems.
  2. 🔗 Catch up on previous discussions and follow current discussions on the forum about highway data updates.
  3. 🔗 Report updates and problems in existing highway systems on the forum.
  4. 🔗 Read and understand the developer manual.
  5. 🔗 Participate in peer review of a preview highway system.
  6. 🔗 Understand the project structure and how highway data is organized on GitHub.
  7. 🔗 Develop a new highway system
  8. 🔗 Take responsibility for updates in an unclaimed region, or by requesting to become the maintainer for a region from someone looking to unload some of theirs