Travel Mapping Manual: How to participate in the project

How to create a user list file

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.

🔗 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.

🔗 Make 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.

🔗 Make a list of highway sections you have traveled.

The Highway Browser is designed to help you with this process. The Highway Browser lists all available systems and routes that you can use. For each route, the Highway Browser also provides a list of waypoints that you can use as a start or end point.

Break up your travels into traveled sections by region and route (we recommend starting with only active systems). For each route section, add one line to your .list file with the following format:

Region Route Waypoint1 Waypoint2

For example, if you traveled in the United States on Interstate 70 in Illinois between Exit 52 and the Missouri border, you would put the following line in your file:

IL I-70 52 MO/IL
- The region and route combination is indicated on the left after .list name: in the Highway Browser.
- Click the start point 52 of your travel segment on the table to center the map at this point.
- Copy the first line of the info window to get the correct name 52.
- Click on the end point MO/IL or click the waypoint on the map to open the info window and copy the label name MO/IL.
- The waypoints at the ends of the traveled segment may be listed in either order.
NEW The .list Tool option helps generating the full .list file line by clicking on the first and last segment of your travel.

You most likely continued your travel in Missouri. If you left Interstate 70 at Exit 249, you would put the second line in your file:

MO I-70 MO/IL 249
- Click the MO I-70 link under Intersecting/Concurrent Routes: on the info window to open the Missouri continuation of Interstate 70 within the Highway Browser.
- Copy the code behind .list name: for your second line in your .list file.
- Then click on the border waypoint to catch the first waypoint, and on exit 249 to get the second waypoint.
NEW The multi-region option helps generating a .list file line which covers a travel on connected routes beyond region borders:

IL I-70 52 MO I-70 249

Continue 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.

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.

🔗 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 mapping script 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.

🔗 Send your .list file by email to travmap@teresco.org destination. Mention in the subject line that your username is a new one.

You have now finished your part! Your file will be included in the next site update, which typically occurs nightly between 9 and 11 PM US/Eastern.

🔗 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.
Lots of stats are available in csv files linked from https://travelmapping.net/stats/.

🔗 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.

NEW 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.

🔗 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.

Travel Mapping's volunteers hope that you enjoy your maps and stats pages from this free service!

🔗 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.

🔗 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, nor other filenames. Note that since usernames generally do not change, the valid filename also generally does not change.

Due to Mac and Windows operating systems hiding the file extension .list by default and/or including an extra, hidden .txt extension, a .list.txt extension is also accepted (e.g., highwayguy80.list.txt). However, users are asked to avoid the double extension so that files do not need to be renamed after being submitted.

🔗 The file was not emailed.

Check that you attached your file to the email you thought you sent, and check that the email was sent. Files that are not received cannot be processed.

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

Site updates typically occur daily, and the time of the last update can be found at the bottom of the project's home page (the most recent update was completed at 2024-10-19 23:07:39 US/Eastern). If your file was sent more than about 30 minutes before the most recent update, you can check on its status with an additional email or simply resend.
Note that occasionally processing may be delayed. Any expected delays will be mentioned in the project forum.

🔗 The new file was processed, but all the highways from the previous file have vanished.

The new file 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 the Highway Browser. The Highway Browser shows the highway as PA I-80 and lists the waypoints as 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, 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 the Highway Browser. Start with Virgina and click on the intersecting route links to change the regions till you've reached New York.

Catch up the entries for your .list which should be read as follows for 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
  
```
Or 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
  
```
🔗 Beltways (full loop highways) within a single region.

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 the Highway Browser:
```
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.
🔗 No waypoint where your travel started or ended.

If the route does not have a waypoint in the Highway Browser where your travel on this highway started or ended, you need to find a nearby waypoint in the Highway Browser.

🔗 Open Highway Browser from a map

Viewing regions or systems on a map helps to see all your traveled segments. Click on the overlays to open the info window. The link directly opens the route in the Highway Browser so that you can create your .list file line.
🔗 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.
🔗 NEW Multi-region .list file line

In addition to the common .list file line with four fields, it is possible to use six fields to cover a multi-region travel on a connected route. For each route section, add one line to your .list file with the following format:

Region1 Route1 Waypoint1 Region2 Route2 Waypoint2

Click View Connected Route in the Highway Browser to load the connected route for all regions. The first line of the waypoint info window comprises the required region, route and waypoint combination to be copied into your .list file. Put both waypoints into the same line:
IL I-70 52 MO I-70 249
🔗 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 problems with the system.

🔗 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.

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:

🔗 Become an active user and get familiar with the project structure. Create a list files and understand how routes are organized into highway systems.
🔗 Catch up on previous discussions and follow current discussions on the forum about highway data updates.
🔗 Report updates and problems in existing highway systems on the forum.
🔗 Read and understand the developer manual.
🔗 Participate in peer review of a preview highway system.
🔗 Understand the project structure and how highway data is organised on Github.
🔗 Develop a new highway system
🔗 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