Importing your own GPX

Tracknotes (the web upload page and the mobile "＋" button) turns a GPX file into a trail guide: a map, an elevation profile, a waypoint list and a plan calculator. This page explains exactly what the importer does with your file, so you can prepare GPX that works well and understand the "Worth knowing" notes it shows after an upload.

The same code runs in the browser, on the phone and in the project's own build, so a file imports identically everywhere.

What goes in

• A .gpx file (GPX 1.0 or 1.1). Up to 50 MB on the web, 20 MB on mobile, at most 100,000 track points in total and at most 20,000 waypoints.
• .tracknotes.json files exported from the web "Export for Tracknotes" button are also accepted on mobile; they skip the pipeline below and load as already-built trails.

Nothing is uploaded to a server unless you choose to share the route with the community. The file is processed on your device and the result is stored locally (IndexedDB in the browser, the app's documents directory on mobile). The other optional network calls are elevation backfill and the points-of-interest search (below).

Step by step

1. Tracks and waypoints are read

• Every <trk> becomes a track; its <trkseg>s are joined end to end.
• If the file has no <trk> at all, all <rte> points are used as a single track called "Route".
• Every <wpt> becomes a waypoint. Its <name>, <desc> and <type> are kept.
• Names, types, elevations and times are read from the element's own children only: the <type> inside a waypoint's <link> (a MIME type) is not its type, the <name> of the <metadata><author> is not the trail's name, and a <trk> without a <name> stays unnamed rather than taking the name of its first point.
• Coordinates are parsed strictly: a point whose lat/lon is not a plain decimal number (-37.1abc, Infinity), or is out of range (latitude beyond ±90°, longitude beyond ±180°), makes the import fail rather than plotting somewhere it is not.

2. The trail is named

In order of preference: the name you type on the import screen, then <metadata><name>, then the first track's <name>, then "Imported trail".

3. Tracks are classified by name

Each track's name is matched (case-insensitively) against these patterns:

The first pattern that matches wins, in the order of the table: a track already named as an alternate stays an alternate even if the word "terminus" appears in it too.

So a file with Day 1, Day 2, Day 3, Side trip: Summit, Alt: High route and Terminus: Chief Mountain produces a three-leg main route, one side trip, one alternate and one alternative trail end.

Alternates and side trips are drawn on the map and listed as variants. They are matched to the main route at both ends (within 500 m) so the guide can show where they leave and rejoin; waypoints within 200 m of a variant are attributed to it. One that reaches the route at one end only is read from that end, whichever way it was drawn, so its waypoints are numbered from the place it leaves the trail.

An alternative trail end is a different way of starting or finishing the walk — a second border monument, a different trailhead — where the far end is deliberately nowhere near the route. It is matched at one end only: whichever end of the track is nearer the main route becomes the junction (so the track works drawn either way round), the other end is left where it is, and no rejoin is looked for. Put a waypoint of <type>endpoint</type> at the far end and the guide names the place the route ends at. It is listed with the side trips and marked Terminus, and it adds nothing to the trail's distance.

4. Main-route tracks are chained into one line

If more than one track is classified as main route, they are joined by geography, not file order: starting from the first track in the file, in the direction it is drawn, the importer repeatedly adds whichever remaining track has an end closest to either end of the route so far, reversing tracks where that closes the gap. A track that fits before the first one is put in front of it, so the first track is never turned round. A gap of more than 100 m between two legs is reported ("…m gap between "Day 2" and "Day 3"") — the route is still built, with a straight line across the gap.

Gotcha: two tracks that overlap or run parallel (say a recorded track and a planned one) will both be treated as main route and chained into a route that walks the trail twice. Delete one, or name it as a side trip or alternate.

5. Big tracks are thinned

Tracks over 5,000 points are simplified (Douglas–Peucker, keeping the shape) down to about 5,000 before anything else is computed, so distances, the profile and waypoint positions all agree. A second, lighter copy of around 3,000 points is made for drawing the map. The report says "simplified" when this happened; distances are unaffected in practice.

6. Elevation is cleaned

• If no point has a usable <ele>, the profile is flat and day estimates are distance-only. The import screen offers to fetch elevation from Open-Elevation; only the track's coordinates (up to 2,000 samples, interpolated between) are sent. A sample the service has no ground for — a hole in its terrain data, which comes back as −32,768 m — is skipped and interpolated over from the samples either side.
• If elevation is present, single-point spikes of more than 50 m are removed, a 7-point moving average is applied, and ascent and descent ignore any rise or fall of less than 3 m: a change only counts once the track has gone 3 m above or below the last height that counted, and then all of it counts. Small ups and downs inside that band are left out however many there are, while a long gentle climb is counted in full however small each step of it is. The trail's totals and each waypoint's climb from the one before are measured the same way, so they add up. Barometric recordings routinely inflate ascent 2–3× without this; if the raw total was more than 1.5× the cleaned one the report says the elevation "looks noisy".

7. The route is checked for doubling back

The importer looks for stretches where the main route retraces itself for 2 km or more and reports them: "The route doubles back on itself for 5.2 km at the end of the route". This is advice, not a problem — a walk into town and back out is a legitimate part of many trails, so nothing is changed automatically. Those kilometres do count twice in the trail length, and any waypoint on the retraced stretch appears twice in the list (the second copy gets a distinct id).

If the section is really a side trip, move those points into their own <trk> named Side trip: … and re-import; step 3 will then lift it off the main route.

A loop that finishes where it started is not doubling back: meeting your own start again is how a circuit ends, so it is not reported unless you also walk part of the way out and back (an access track to the loop, say).

8. Waypoints are placed on the route

Each waypoint is snapped to the nearest point of the main route. Waypoints within 500 m of the route get a km position and show in the list and on the profile; anything further away is kept as "off-trail" (on the map, not in the distance list). The report gives both counts. On a loop, a waypoint at the trailhead is listed once, at km 0, not again at the finish.

9. Waypoints are given a type

A waypoint's type is the whole reason the guide can plan: it decides the icon, whether the point counts as water, and whether it counts as a place to buy food. The types the guide understands are campsite, hut, water, water-tank, town, resupply, food, accommodation, caravan-park, trailhead, road-crossing, inlet-crossing, side-trip, mountain, beach, endpoint, poi, and waypoint for "not categorised".

The type is decided by the first of these that produces an answer:

1. The GPX <type> element, taken as-is and never overridden. If your file says <type>campsite</type>, that is the type — including a word of your own the guide has never heard of, which is kept verbatim and shown with a tidied-up label.

2. A prefix on the name, which is then stripped from the name:

   Prefix	Type	Prefix	Type
   C:	campsite	TH:	trailhead
   W:	water	CP:	caravan park
   WT:	water tank	IC:	inlet crossing
   H:	hut	ST:	side trip
   T:	town	M:	mountain
   F:	food	S: / E:	start / end point

   A space works instead of the colon (C Long Gully), and road crossings are the space form only: R Bogong High Plains Rd. The delimiter is required, which is why Campsite Area and Eastern Access are left alone rather than being read as C- and E-prefixed.

3. A built-in list of Australian trail towns (Alice Springs, Walhalla, Pemberton, Quorn and about two dozen others) → town. This outranks prefixes, so Mt Hotham is a town rather than a mountain.

4. Words anywhere in the name — see below. Imported files only.

5. Otherwise the waypoint is left not categorised, rather than guessed at.

Types guessed from the name

Most GPX files in the wild use none of the conventions above: they just have names like Wallaby Creek Campsite or Coles Supermarket. So for a file you import, the guide reads the name for these words. (Trails built into the app skip this step — their waypoints are already categorised by hand, and guessing would only add noise.)

Whole words only, plurals included, so Huts matches and Hutchinson does not; earlier rows win, so Caravan Park is not read as parking and Side trip: Mt Ossa is a side trip rather than a mountain. The name itself is never changed by this step — only a prefix is ever stripped.

Some words are deliberately not used, because in Australian place names they mean the wrong thing far too often: bare creek, river, spring, dam and well are not read as water (Falls Creek is a town, Spring Gully is a road), bare camp is not read as a campsite (Camp Road), and a town is never guessed from its name, because inventing a resupply would quietly shorten how much food the plan tells you to carry. A pub is filed as accommodation rather than food for the same reason: accommodation never counts towards resupply, so a guess can never make a food carry look shorter than it is.

The import report tells you how many waypoints were typed this way and how many are still uncategorised.

Fixing a category

Guessing from words is never going to be right every time, so on an imported trail's page you can set the category yourself: open a waypoint's row in the waypoint list and choose from the Category menu. The change is saved with the trail and is picked up by the plan calculator, the map icon and the water/food filters. Trails built into the app are read-only.

What the types are used for

• Town, food and resupply points are the resupply stops: the plan calculator measures food carries between them, and the waypoint list can be filtered down to just these to read the leg distances off directly.
• Water and water tank points drive the water-carry distances and the water filter.
• Campsites and huts are the candidate overnight stops when the plan splits the walk into days.
• Accommodation and caravan parks are shown but deliberately not counted as resupply — a bed is not a shop.

Common words other people's files use are understood as aliases here even though the guide never writes them itself: a waypoint typed spring, creek, tap or bore counts as water, and one typed supermarket, store, roadhouse or post-office counts as resupply.

Places you leave the trail to reach

A town is often nowhere near the route: you leave at a road crossing and hitch, walk or catch a shuttle the rest of the way. A file can say so, by hanging a few extra fields off the waypoint that marks the turn-off:

<gpx xmlns="http://www.topografix.com/GPX/1/1"
     xmlns:tn="https://tracknotes.app/xmlschemas/gpx-waypoint/1">
  <wpt lat="38.4967" lon="-106.3244">
    <name>Salida</name>
    <type>town-access</type>
    <extensions>
      <tn:offTrailKm>35.4</tn:offTrailKm>
      <tn:accessMode>hitch</tn:accessMode>
      <tn:acceptsBoxes>true</tn:acceptsBoxes>
      <tn:store>full</tn:store>
      <tn:accessName>Monarch Pass (US 50)</tn:accessName>
    </extensions>
  </wpt>
</gpx>

• offTrailKm is how far the place is from the route, one way, in kilometres.
• accessMode is how you cover that distance: foot, hitch, shuttle, boat, or on-trail for somewhere the route runs straight through.
• acceptsBoxes says whether the place will hold a resupply box you post ahead.
• store says what the place sells: full (a supermarket or grocery — a whole carry), limited (a general, convenience or camp store — a top-up), meals (a cafe, pub or lodge: food to eat there, perhaps a parcel to collect, nothing to carry out) or none (no shop). The planner shows it as "Full resupply", "Small store", "Meals / parcel only" or "No shop" — "Box only" for a none place that takes boxes. Any other value is ignored, and a place without one shows nothing.
• accessName names the turn-off itself, which is what a list of options at one road end is grouped under.
• offTrailAscentM and offTrailDescentM are the metres climbed and descended walking in, from the route to the place; walking back out climbs the descent and descends the climb.

A place you walk to (foot, or no mode and 5 km or less) is counted wherever the guide measures a walk:

• in the day planner, a night there adds the walk in, with its climb, to the day that reaches it, and the walk back to the day after;
• a water carry that starts or ends at a water source off the route includes the walk out of it or in to it;
• a resupply leg counts the walk to the town and back, with its climb both ways, in its time and food — all of it on the leg that reaches the town;
• on the phone, the "From your location" card on a place's page adds the walk's climb and time to the trip there.

A place you ride to is not walked, so it adds nothing to any of them: the ride is reported, never timed.

All six are optional and all six are read on import, so a hand-made file can describe a turn-off exactly the way the built-in trails do. They have to be direct children of <extensions>; anything the guide cannot read — an accessMode that is not one of the five words, an offTrailKm that is not a number — is left off rather than guessed at, and another program's <extensions> block is ignored. Nothing here changes the route: a turn-off is a point on the trail at the kilometre where you leave it, not the place itself.

There is no field for the way itself. The built-in trails also carry the line of each walk in, found over OpenStreetMap when the trail is built, so the map can draw it dotted from the route to the place. An imported GPX file has no such line, and none is made for it: the map shows the place where it is, without the dotted way in, and every distance and climb above still counts. The same goes for a route shared with the community, which keeps these six fields but never a line: the server rebuilds every shared route from its own coordinates, and a line it was handed is not something it can check. A .tracknotes.json file exported from the website is a copy of a trail already built, so it keeps any line the trail has.

10. Identity

• The trail id is u_ followed by a hash of the file's contents, so importing the same file twice updates the existing guide instead of adding a duplicate. Changing anything in the file makes a new guide.
• Waypoint ids are minted locally (uw_…) and never sent to the comments service; imported trails have no shared comments.

Points of interest (optional)

Waypoints come from your file. Points of interest come from OpenStreetMap, and they are opt-in: on an imported trail's page, Find points of interest searches a 2 km-wide corridor along the whole route — the main line plus every alternate and side trip — for water, campsites, shops and other resupply, transport, and emergency services.

• The search runs from your browser straight to OpenStreetMap's Overpass API. Nothing is uploaded to us, but the shape of your route does leave your device: the query is the route corridor. This is the only step besides elevation backfill that touches the network.
• A long trail is split into several queries, sent one at a time a couple of seconds apart because that is what the free Overpass servers ask for. A route of a few hundred kilometres takes a minute or two. Progress shows which area is being fetched, and Cancel stops it — nothing is saved until it finishes.
• If some areas fail (a busy server, a dropped connection) the results from the rest are still kept, and a note tells you the coverage is partial. Searching again retries.
• Results are stored with the trail in this browser, like everything else about an import, and are included when you export the trail for the mobile app, where they appear on the map, in the list and on the elevation profile.

On the phone, a GPX imported in Tracknotes can search for its own: open the guide's map, tap the layers button (◫) and choose Find places along this route. The screen says how many requests the search makes, roughly how much data it will download and whether you are on Wi-Fi or mobile data before anything is sent; the search starts only when you tap Search OpenStreetMap. It runs the same corridor queries as the trail build, tries a second and third public Overpass server for any query the first one refuses, and cleans the results the way the bundled trails are cleaned (noise such as ordinary bus stops dropped, places that duplicate one of your waypoints folded into it, city stretches thinned). Cancel leaves the guide unchanged; if some areas get no answer the rest are saved and Retry the missed areas asks again for just those. The results are saved into the guide, so they work offline afterwards, and Remove points of interest on the same screen takes them out again.

Points of interest are kept separate from your waypoints. They are shown on the map, never merged into the waypoint list, and never counted by the plan calculator — an OSM tap is not a water source you have checked. Nothing about your file is changed by the search, and Remove points of interest deletes them again in a click. If a point turns out to matter, add it to your GPX as a proper waypoint and re-import.

Point-of-interest data is © OpenStreetMap contributors and is used under the Open Database License; the attribution is shown on the trail page whenever POIs are loaded.

Sharing with the community

Once a trail is saved, the upload page offers Share with the community (when the site is connected to the Tracknotes service). A shared route is listed for everyone on the website and in the app, grouped by country and region.

• It needs your app identity. Sharing is tied to the Tracknotes app on your phone: if this browser is not linked yet, the page asks for the code from Settings → Linked browsers. That is what lets you edit or delete the route later.
• You describe it. A name, a description (at least 20 characters), an optional credit or source line, and the country and state or region it is in.
• It is checked before it goes up. The same automatic checks run in your browser while you fill in the form and again on the server: the route must be a valid trail between 1 and 5,000 km with at least 20 points, its distances must add up, and the text must be the right length. Warnings — no elevation, a large jump between points, speeds that look like a drive (read from the GPX file's timestamps, so only when the file is included) — don't stop you, but are shown to reviewers. Any failure does, and the list says which.
• It is public domain. You confirm that you recorded the track yourself or that it is openly licensed, and you release it under CC0. The route, its text and your display name are public; recording times are not (they are dropped from the processed route). The original GPX file is sent too unless you untick Include the original GPX file — a raw file can carry your name, device and recording times — and is kept privately for re-processing, never published. A file over 5 MB is always left out.
• It is listed straight away as Unverified. An automated review (Anthropic's Claude) reads the text and a summary of the route in the background, and a person marks it Verified after checking it. Until then the route carries an Unverified label. Anyone with a linked browser (or the app) can Report a route, except its owner; one that collects several reports is hidden until an admin looks.
• You stay in charge of it. The route's page lets you edit its name, description, credit and region (an edit to a Verified route returns it to Unverified), or delete it. To replace the track itself, share the new file and delete the old route.

Anyone can open a community route's page, see it on the map and profile, and Save to my trails to plan with it like one of their own imports.

Reading the "Worth knowing" notes

Alongside these notes the report counts categorised from their names and not categorised — how many waypoints were typed from their words in step 9, and how many are still uncategorised and worth setting by hand.

Preparing a good file

• One <trk> for the whole walk, or one per day/leg — both work.
• Name side trips and alternates so they are recognised (Side trip: …, Alt: …), and an alternative start or finish as Terminus: … with an endpoint waypoint at its far end.
• Put useful waypoints in the file, and give each one a category the importer can see, so the plan calculator can use it. Any of these works: a <type> element, a prefix on the name (C:, W:, T:…), or simply a descriptive name — Wallaby Creek Campsite and Water tank at the shelter are both categorised correctly on their words alone. Water sources and food stops are the two that change the plan, so they are the two worth getting right.
• Anything the importer could not categorise is listed in the report, and you can set its category from the trail page afterwards — no need to edit the file and import again.
• Keep the route walking in the direction you want km 0 to be; the guide can be reversed on screen, but the file's first point is the start.
• Include <ele>, preferably from a DEM-corrected export rather than a barometer, for the best ascent figures.