Providing Trail Data
This documentation is for anyone who plans to create data meant for upload into the To The Trails application.
The data format for To The Trails data files is specified in the trail data standard.
Required data fields are described in that document, and descriptions of the three types of trail data are included in the user documentation.
It is recommended that the first time you upload data, you check examples of existing data to verify that your column/field names match what the system is expecting. For live examples of the data, see the following JSON endpoints:
NOTE (10/31/2013): Replace "tothetrails.com" with "trailsyserver-prod.herokuapp.com" for the next few days. The URLs will be moved to tothetrails.com soon.
- http://tothetrails.com/trails.json for trail data. (http://tothetrails.com/trails.csv provides the trail data in CSV format for editing and re-uploading.)
- http://tothetrails.com/trailheads.json for trailhead data.
- http://tothetrails.com/trailsegments.json for trail segment data.
Note that while the system accepts a CSV file for the trail data, and shapefiles for trailhead and segment data, these URLs return GeoJSON responses. GeoJSON files are also accepted by the system for all three types of data, so these responses may be saved, modified, and re-submitted to the application if desired. Modern GIS software should be able to import these files.
(Side note: The trails.json endpoint URL returns GeoJSON even though is doesn't contain any geospatial data used by the application. It includes a single point [0,0] for each trail in order to satisfy our GeoJSON parser/generator. That point is ignored by the uploading parser if the file is re-submitted. The trails.csv URL does not include the dummy point.)
NOTE: Uploading data for trails, trailheads, or segments will REPLACE all currently existing data for that type of item, including any edits that have been made by hand in the administrative interface. (The only exception to this rule is that as long as a trail name does not change in a new upload, trail data uploads will retain their existing photos.)
To upload a new set of trail, trailhead, or trail segment data:
-
Click on the tab for trails, trailheads, or segments in the left navigation bar.
-
Near the top of the page, you'll see a form which will allow you to upload a file for that type of object.
-
Before uploading new data, it is strongly recommended that you download your current data first. There is a link to your organization's current data near the top of the page (to a CSV file for trail data, and a GeoJSON file for trailhead and segment data). Click that link and use your browser's "Save As..." feature to save this file to disk. If something happens while you're uploading new data, you can then upload this downloaded file to restore your previous data.
-
Then, click on "Choose File..." to select your new data file from your system.
-
Next, test out the upload by making sure the "Replace Existing Data" checkbox is unchecked, and that the upload button says "Test Upload". Then click the "Test Upload" button. Your current data in the system will be untouched, but you will see a screen that shows what would happen if you were to replace your existing data with the data in the file you're uploading.
-
Look at the upload results table and make sure that the data you're adding is being understood and accepted by the system. If there are unaccetpable problems with the file, correct the file and go back to the previous page to submit the corrected version.
-
Once you are sure that the new data you're uploading is acceptable, hit the back button, re-select the file using the "Choose File..." button, and click the "Replace Existing Data" checkbox. Then click the "Upload Data" button (which is the same button that you clicked before when it was named "Test Upload"), and wait for confirmation that your data has been uploaded and has replaced your previous data.
-
Again, if anything goes wrong in the process, you can submit the file you downloaded earlier to return your data to its previous state.
All geodata provided in all organizations' trail segments file is displayed in the public application at higher zoom levels, whether or not each individual segment is part of a listed trail. This helps show users the full extent of the local trail network, including sections like connector trails that don't merit metadata or searchability. If a user hovers over a particular segment, all of the trail1-trail6 fields for that trail segment will appear in a popup.
For a trail:
- to appear in the list of trails in the informational panel,
- to be searchable using that panel,
- to have metadata displayed for it,
Its name needs to appear in three different places:
- as the "name" field for a record in the trail metadata
- in one of the trail1-trail6 data fields for at least one trailhead
- in one of the trail1-trail6 data fields for at least one trail segment
It must be an exact match in all three locations. If a trail name does not exist in all three locations, it will not be browsable in the list of trails, or searchable, and its metadata will not be displayed anywhere in the public application.
If a trail you expect to see listed is not, check for its name in all three locations.
There is no way currently to add individual records for trails, trailheads, or segments. You need to upload all of your information at once, at which point all existing data for that data type is replaced.
It's recommended that to add a record, you download the existing data in the system using the link provided on the trail, trailhead, and segment listing pages, import that into the GIS system (for GeoJSON files) or spreadsheet application (for CSV files) of your choice, add your new information there, and save out your updated information as a new file to upload.
Note that there are several fields in the data standard that are not used in the application. Some of these fields are ignored by the uploader, but segment-specific access/use fields (such as "dogs", "equestrian", "xcntryski", and so on) are stored in the database and returned in the data provided at the trailsegments.json endpoint above. While segment-level access/use fields are not used in the current application, trail-level access/use fields are used.
Future versions of this app, or other applications, may end up using this segment-level access/use data. It's recommended that you provide this data if it's available in case it turns out to be useful to later versions of this or other applications.