Travel Mapping Manual: How to participate in the project

• How to create a user list file
• Travel Mapping data basics
• First steps with email submission
• Solutions to common problems
• More examples of how to break down your travels
• Advanced features
• How to become a highway data manager

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.

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.

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 travmap@teresco.org.
   
   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 https://travelmapping.net/stats/.


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!

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-12-20 21:19:33 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.

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

• 🔗 Highway segment within a single region.
  
  For the segment of I-80 between Exits 161 and 224 in Pennsylvania, USA, look up the highway and waypoint labels for those interchanges in showroute. The highway is PA I-80 and the waypoints are 161 and 224. Enter the following line into your .list file:
  

  PA I-80 161 224
    

• 🔗 Highway segment crossing into multiple regions.
  
  To enter the segment of I-81 between Exit 300 in Virginia and Exit 10 in New York, the easiest approach is to add a multi-region line by specifying the first waypoint in West Virgina and the last waypoint in New York only:
  

  VA I-81 300 NY I-81 10
    

  Alternately, you can break up the segment into smaller pieces by region. The Virginia segment begins at Exit 300 and ends at the West Virginia border, so use waypoints 300 and VA/WV for the Virginia segment. I-81 runs from border to border in West Virginia, Maryland, and Pennsylvania, so use waypoints WV/MD, MD/PA, and PA/NY for these states. The New York segment begins at the Pennsylvania border and ends at Exit 10, so use waypoints PA/NY and 10. All of these waypoints are listed in showroute. Start with Virgina and click on the intersecting route links to change the regions until you've reached New York.
  
  Ultimately your .list should contain all of the following to map the whole segment:
  

  VA I-81 300 VA/WV
  WV I-81 VA/WV WV/MD
  MD I-81 WV/MD MD/PA
  PA I-81 MD/PA PA/NY
  NY I-81 PA/NY 10
    

• 🔗 Beltways (full loop highways) within a single region.
  
  The .list Tool in showroute is especially helpful in creating .list file entries for beltways. The remaining description here is included as an explanation for those who wish to construct .list file entries manually.
  
  In single-region beltways, a waypoint has been selected as both the highway's beginning and end. This location is used for both the first and last waypoints of the highway, with a different waypoint label for each end. If the segment you wish to enter into your .list file crosses that point, split your segment into two at that point.
  
  Consider first the segment of the Baltimore Beltway (MD I-695) between Exits 17 and 31 along the northern side of Baltimore. I-695 begins and ends at a southern waypoint called both 0 and 48. Since the waypoints run continuously from 17 to 31 without crossing that southern point (compare to next example), treat this segment simply as beginning at waypoint 17 and ending at waypoint 31:
  

  MD I-695 17 31
    

  Now consider the southern segment of the Baltimore Beltway between the same Exits 17 and 31. The waypoints numbers reset in this range: 17, 16, ..., 1, 0, 48, 44, ..., 31. Waypoints 0 and 48 refer to the same point. With this in mind, treat your whole segment as two, one with ends at 0 and 17, and the other with ends at 31 and 48:
  

  MD I-695 0 17
  MD I-695 31 48
    

  To enter the entire Baltimore Beltway, use the two labels for the common end points, which are the first and last labels shown in showroute:
  

  MD I-695 0 48
    

• 🔗 Beltways crossing into multiple regions.
  
  Treat segments along these beltways just as you would any other segment that crosses into multiple regions: one .list file line per region, or a multi-region 6-field entry that spans regions. Again, the .list Tool in showroute is especially helpful in creating .list file entries for beltways.
  
  
• 🔗 No waypoint where your travel started or ended.
  
  If the route does not have a waypoint where your travel on this highway started or ended, you need to find a nearby waypoint in showroute. Our manual includes a section on how we determine which points are included in each route.

• 🔗 Using comments
  
  Just as is the case in programming languages, Travel Mapping allows you to add comments to your .list file. All text on a given line after a # is treated as a comment, and is ignored by the site update process. You can comment out entire lines, or use them to include an annotatation at the end of the line.
  
  #My first travel section
IL I-70 52 MO/IL #This is the section in Illinois
MO I-70 MO/IL 249 #This is the section in Missouri
  
  
• 🔗 Structure .list file
  
  Many users break up .list files into chunks by system, region or individual travel to make it easier to read or manage. You can also use blank lines as desired to enhance readability.
  
  
• 🔗 GitHub submission
  
  When you submit a .list file, it is placed under source code control using GitHub. Instead of emailing updates, some users fork our GitHub repository at https://github.com/TravelMapping/UserData and submit a pull request.
  
  Using GitHub directly is by no means required. Unless you are an experienced Git/GitHub user, it's usually best to submit at least your initial file by email to ensure it ends up in the correct location and does not have any problems that would cause errors during the site update process.
  
  🔗 Initial setup to use GitHub directly:
  
  1. 🔗 Sign up on https://github.com and create your own GitHub user.
  2. 🔗 Go to https://github.com/TravelMapping/UserData.
  3. 🔗 Press Fork at top of the page.
  4. 🔗 Click on your GitHub user name icon.
  
  🔗 To be done with every modification of your user list file:
  1. 🔗 Go to your user list file: https://github.com/<your GitHub user name>/UserData/blob/master/list_files/<your Travelmapping user name>.list.
  2. 🔗 Click on the Edit this file icon.
  3. 🔗 Make your edits or copy the content of your offline user list file.
  4. 🔗 Select Commit directly to the master branch on the bottom of the page.
  5. 🔗 Press Commit changes.
  6. 🔗 Go to https://github.com/<your GitHub user name>/UserData (link on top of the page).
  7. 🔗 Press Pull request.
  8. 🔗 Check your changes indicated in green and red.
  9. 🔗 Press Create pull request.
  10. 🔗 Press Create pull request again.
  Your pull request will be merged by an admin before the next site update.
  To undo your changes, press Close pull request.
  
  
• 🔗 Data verification
  
  For advanced users, it is possible to check the changes to the .list file by running the site update to create the user log file before submitting the GitHub pull request. You can use the data verification tool.
  
  

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:

listname;description;includeInRanks

The listname is the TM username (case sensitive), 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 travmap@teresco.org or by submitting a pull request in the repository.

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