Back to Support / Building a hike

Importing a hike

Building a hike in your own tools and bringing it in as a file, updating a hike from a file, with the format, the limits and a complete example.

You don't have to build a hike on the map. If you'd rather write it in a text editor, a spreadsheet or a mapping tool, you can put it in a file in the HistoricTrails hike format and import it. The format is public, so any tool that can write the file works.

  • Importing creates a draft that only you can see. Nothing is published until you press Publish in the builder.
  • A file can also update a hike you maintain: see Updating a hike from a file.
  • A new hike from a file counts toward the limit of 10 new hikes an hour. You can also try up to 30 imports an hour, counting files that turn out to have problems.
  • A file can list photos that are already on HistoricTrails.org, as links: see Photos. Other photos are added in the builder once the hike is in.
  • A new hike is labeled with the language you're using the site in, the same as a hike you start with New hike.

The current format is version 3. Files in versions 1 and 2 still import: see What changed in version 3.

Step by step

  1. Start from the example. Download the example file and open it in any text editor. It's a complete, working three-stop hike you can change into your own.

  2. Set the place. In place, put the two-letter country code ("US"), the state or province code without the country in front ("GA", not "US-GA"), and the city.

  3. List your stops in walking order. The first stop in the list is stop 1. Each stop needs a name, a lat (latitude) and a lng (longitude). To get a stop's numbers:

    • OpenStreetMap: right-click the spot on openstreetmap.org and choose Show address. The numbers shown are latitude, then longitude.
    • Google Maps: right-click the spot. The first line of the menu is latitude, then longitude; click it to copy them.

    Latitude is the one between -90 and 90 (north of the equator it's positive). In the Americas, longitude is negative.

  4. Add the trail start, and the trail end if the hike is one way. The start is where people begin: a trailhead, a place to park, a transit stop, or more than one of these. On a hike that finishes somewhere else, the end says where, and getting_back tells people how to return. See Trail start and trail end.

  5. Write the stories. Give each stop a story: what happened there and what to look at. Plain text is fine; leave a blank line between paragraphs.

  6. Add quiz questions if you like. Each question has two to five choices, and exactly one of them has "correct": true.

  7. Add the walking path if you have one. The path is a GeoJSON LineString, the same shape most mapping tools export as GeoJSON. You can leave it out: the hike then walks in straight lines from the trail start through each stop to the trail end, and you can shape it in the builder afterward.

  8. Check that the file is valid JSON. Any JSON checker will point out a missing comma or quote. Editors that understand JSON Schema can check the whole file against the published schema as you type.

  9. Import it. In My Hikes, press Import a hike, choose the file, and press Import. If everything checks out, the new draft opens in the builder. If the file has the code of a hike you maintain, you're asked first whether to update that hike or create a new one.

Path points are longitude first. Stops use named lat and lng fields, but each point of the path is [longitude, latitude], the GeoJSON order. [-81.0916, 32.0799] is in Savannah; [32.0799, -81.0916] is in Antarctica. If the importer says the hike doesn't fit in one area, or that a stop is far from the path, check this first.

How stops and the path fit together

The stops and the path are two separate lists in the file. Nothing in a stop points at a particular path point; the site connects them by where they are:

  • Stops stay exactly where you put them. Their lat and lng are never changed.
  • Each stop has to be near the path. Every stop, the trail start and the trail end must be within 100 m (about 330 feet) of the path, and the path has to reach the stops in the same order as the stops list, with the trail end after the last one. A stop farther away, or out of order, is listed as a problem.
  • The path is bent to touch each stop. Where the path runs beside a stop, the stop's own coordinate is added to the path at the closest spot, so the path passes exactly through it. The path is also made to begin at the trail start and finish at the trail end.
  • No path? The hike walks in straight lines from the trail start through each stop to the trail end, in order.

This means a track from another app and a separate list of places work together without any extra linking, as long as the places sit along the track. A hike exported from this site already has every stop's coordinate in its path, so it imports without any bending.

What happens when you import

The site checks the whole file and lists every problem it finds at once, each with where it is in the file. Distances in the list use the units you've chosen on the site. The checks of where things are (the area, how far each stop is from the path, and the walking distance) need every stop, trail start, trail end and path coordinate to be a valid number, so if one isn't, fix it first and those checks run on your next try. If there are no problems, the site creates the draft:

  • The walking path is bent so it passes through every stop. Stops are never moved, and nothing you drew is removed; where the path runs beside a stop, a point is added at the stop.

  • Distance, walking time and difficulty are measured from the path, the same as for any hike. So is whether the hike is a loop or one way. None of these is read from the file.

  • Rich text is cleaned: simple formatting stays and anything else is removed (see "Text" below).

  • Photos the file links to are put on the hike and its stops, in the order the file lists them (see Photos).

Then open each step in the builder to check the result, add photos, and publish when you're ready.

Trail start and trail end

The start is where the hike begins. It isn't a numbered stop: it has no story, quiz, photos or stop time. Give it a name and its lat and lng, and say what it is with three switches:

  • "parking": true for a place to park.
  • "transit": true for a transit stop: a train, subway, light rail, streetcar or bus stop. Put the station's name in name.
  • "restrooms": true when there are restrooms here.

Any of them can be true together, and all can be left out for a plain trailhead.

The end is where a one-way hike finishes. It's optional, takes the same name, lat, lng, parking, transit, restrooms and notes, and can also have getting_back: how people get back to the start, for example "Ride the Green Line two stops to Roosevelt, then transfer to the Red Line toward Howard." A stop can sit right beside the trail end.

Loop or one way

There's no field for it: the site works it out from the path.

  • Loop: the path finishes within 200 m (about 660 feet) of where it began (the trail start, or stop 1 when there's no trail start). The walk back counts toward the hike's distance and time.
  • One way: the path finishes farther away than that. The distance and walking time stop at the finish, and a ride back is never counted.

A loop finishes where it began, so a file that gives a loop a getting_back is listed as a problem.

What changed in version 3

  • parking is replaced by start, with the parking and transit switches. A version 3 file that still says parking is listed as a problem.
  • The new, optional end says where a one-way hike finishes, with getting_back.
  • Exported files are written in version 3.

Files in version 2 and version 1 still import as before. Their parking becomes a trail start with Parking on, and they have no trail end. Version 2 is version 1 plus the hike's code and photo links.

The hike's code

Every hike on HistoricTrails.org has a permanent 7-character code, the one at the end of its address. A file exported from the site carries it as code.

  • When you import a file with the code of a hike you maintain, you're asked what to do: Update this hike or Create a new hike. See Updating a hike from a file.
  • A file with no code, or with the code of a hike you don't maintain, always creates a new hike, which gets a code of its own.
  • Leave code out of a file you write yourself for a new hike.

Photos

A file can list photos that are already on HistoricTrails.org, as links. A link is the photo's address and nothing else, for example { "url": "https://historictrails.org/storage/…/photo.jpg" }.

  • Where it's listed is where it goes. photos beside stops lists the hike's own photos; photos inside a stop lists that stop's photos. Each list is in the order the photos are shown.
  • The hero. Add "hero": true to one photo in the whole file to make it the hike's main photo.
  • Only photos you can use. You can link photos you uploaded to the site, the same photos Your photos in the builder offers you. When you update a hike, a photo already on that hike in the same place can stay too, whoever uploaded it.
  • No caption, license or credit. A photo keeps its own caption, license and credit wherever it's used, so a link can't carry them. A link with caption, license, creator_name or creator_link is listed as a problem; change a caption in the builder instead.
  • Limits. Up to 40 photos on the hike and 5 on each stop, and each photo once in each place.
  • Nothing is downloaded. A link to an address that isn't on this site is listed as a problem. Add photos from elsewhere in the builder.

A file exported from the site lists every photo on the hike this way. The address of a photo on a hike that isn't published can stop working after the hike is published again; export again to get its current address.

Updating a hike from a file

You can change a hike you maintain by exporting it, editing the file in your own tools, and importing it again.

  1. Get the hike's file from your data export. It carries the hike's code.
  2. Edit it: rename stops, rewrite stories, add or remove stops, reorder or remove photo links.
  3. In My Hikes, press Import a hike and choose the file. The site recognizes the code and asks what to do.
  4. Choose Update this hike, or Create a new hike to leave that hike as it is and make a new one from the file.

Update this hike replaces the hike's draft with the file:

  • The draft becomes exactly what's in the file: the text, the place, the stops, the path, the quiz questions and the photos. Anything the file leaves out is removed from the draft: a stop that isn't in the file is deleted, and a photo that isn't listed is taken off its stop or the hike.
  • Stops are matched by name or by spot. A stop in the file with the same name or the same location as one of the hike's stops updates that stop, and its photos stay with it. Between two matched stops, any unmatched stops are paired up in order. Stops left over in the file are added, and the hike's stops with no match in the file are deleted. So removing a stop from the middle of the file deletes just that stop; the stops after it stay as they are.
  • Photos under review stay put. A photo hidden after a report isn't in your exported file, and updating leaves it where it is, including as the hike's main photo when the file doesn't mark another one.
  • Your current draft is saved first, as a version in Version history. To undo the update, restore that version. Restoring brings back the text, stops and path, and puts back photos the update took off. It doesn't take off photos the update added; remove those in the builder.
  • Nothing goes live until you publish. On a published hike you land on See exactly what will change, so you can check the update before you publish it. That includes photos: a photo the update takes off, or a stop it deletes with its photos, stays on the public page until you publish.
  • Some things stay as they are: the cover, the hike's language and its code. A souvenir stays as the site set it.
  • Updating doesn't count toward the limit of new hikes.

Reading the problem list

Each problem shows where it is in the file, like /stops/2/lat, and what's wrong. Counting in that path starts at 0, so /stops/2 is the third stop and /stops/2/quiz/0 is its first question. The message itself counts from 1 ("Stop 3 (“Wright Square”): …"). A problem marked (whole file) is about the file as a whole, like a missing comma.

Limits

Imported hikes have somewhat tighter limits than hikes built on the map, so that every imported hike can still be edited in the builder.

What Limit
File A .json file of 1 MB or less, UTF-8 text
Stops 3 to 30
Trail start, trail end None or one of each
Walking distance Up to 15 miles (24 km)
Whole path, including rides and optional stretches Up to 30 miles (48 km)
Area Every stop, trail start, trail end and path point fits in one 40 km (about 25 mile) square
Path 2 to 1,500 points
Stops and the path Every stop, trail start and trail end within 100 m (about 330 feet) of the path, in walking order
Quiz Up to 5 questions per stop; 2 to 5 choices each; exactly one correct; no two choices the same
Title 150 characters
Summary 500 characters
History introduction, planning notes 20,000 characters each
Stop, trail start or trail end name 150 characters
Story 10,000 characters
Trail start or trail end notes, getting back 2,000 characters each
Visitor hours, fees 200 characters each
Visitor notes 500 characters
Question 300 characters
Choice 150 characters
City 100 characters

Field reference

The hike

Field Required What it is
format Yes Always "historictrails-hike".
version Yes 3 (the current version), 2 or 1.
code No The hike's 7-character code. See The hike's code. Version 2 and later.
$schema No The schema's address, for editors that check files as you type. Ignored on import.
language No "en" or "es": the language the text is written in. The hike takes the language you're using the site in.
title No The hike's name. Left out, it's named after its place, like "Savannah Historic Hike".
summary No One or two sentences for the hike's card. Plain text.
history_intro No The history introduction: what kinds of history and experiences hikers will see.
planning No Planning notes: parking, restrooms, hours, what to bring.
place Yes Where the hike is. See below.
start No The trail start: where the hike begins. Not a numbered stop. See below.
end No The trail end: where a one-way hike finishes. Not a numbered stop. See below.
stops Yes The stops, in walking order. See below.
photos No The hike's own photos, as links. See Photos. Version 2 and later.
path No The walking path. See below.
meta No Anything you want to keep with the file. Ignored on import.

place

Field Required What it is
country Yes Two-letter country code, like "US".
subdivision No The state or province code within that country, like "GA".
city No The city or town, as you'd write it. It doesn't have to be on the site's list.

start

Field Required What it is
name Yes For example "Bryan Street Garage", or a station's name.
lat, lng Yes Latitude and longitude.
parking No true for a place to park.
transit No true for a transit stop.
restrooms No true when there are restrooms here.
notes No What to know there, like how parking works.
next_leg No How you get from the trail start to stop 1. See next_leg.

end

Field Required What it is
name Yes For example "Forsyth Park Fountain", or a station's name.
lat, lng Yes Latitude and longitude.
parking No true for a place to park.
transit No true for a transit stop.
restrooms No true when there are restrooms here.
notes No What to know there.
getting_back No How to get back to the start. One-way hikes only.

In a version 1 or 2 file, the trail start is parking, with name, lat, lng, notes and next_leg.

Each stop

Field Required What it is
name Yes The stop's name. Plain text.
lat, lng Yes Latitude and longitude, as numbers (not in quotes).
story No What happened here and what to look at.
visitor_info No hours, fees and notes, each optional plain text.
restrooms No true if there are restrooms.
stop_minutes No Suggested time at this stop, in minutes. See below.
next_leg No How you cover the stretch leaving this stop.
quiz No Up to 5 questions. See below.
photos No The stop's photos, as links. See Photos.

stop_minutes

How long you suggest people spend at the stop, as a whole number of minutes (not in quotes). A stop keeps one of these: 0 (pass by), 5, 10, 15, 30, 45, 60, 90, 120, 150 or 180.

Any other number is rounded up to the next one on that list, so 9 becomes 10 minutes and 16 becomes 30. Anything over 180 becomes 3 hours. A negative number, or one with a decimal like 7.5, is listed as a problem. A stop without stop_minutes gets 5 minutes. The trail start and trail end have no stop time.

The hike's time is its walking time plus these; see Time and difficulty.

next_leg

Field What it is
mode "walk" (the default), "trolley", "ferry", "bus", "train" or "drive". Anything but walking counts as a ride, not walking miles.
optional true for a side trip people can skip. It's counted separately from the main walk.

Each quiz question

Field Required What it is
question Yes The question. Plain text.
choices Yes Two to five answers, each { "text": "…" }. Mark the right one { "text": "…", "correct": true }.

path

Field Required What it is
type Yes Always "LineString".
coordinates Yes The points of the path in walking order, each [longitude, latitude]. A third number (altitude) is allowed and ignored.

Text

The story, history_intro, planning, getting_back and the trail start and end notes fields take plain text or simple HTML. In plain text, a blank line starts a new paragraph. In HTML, paragraphs, line breaks, bold, italic, underline, strikethrough, lists, quotes, headings and links are kept; anything else is removed. Every other field is plain text.

Field names must be spelled exactly as above. A field the format doesn't have is reported as a problem, so a typo like stroy never goes unnoticed.

A complete example

This is the example file in full: a one-way walk from a bus stop to a park, with a way back. It has no code and no photos, so it always creates a new hike:

{
    "$schema": "https://historictrails.org/formats/hike-v3.schema.json",
    "format": "historictrails-hike",
    "version": 3,
    "language": "en",
    "title": "Bull Street Squares Historic Hike",
    "summary": "A short one-way stroll down Bull Street through three of Savannah's historic squares, from the riverfront to Forsyth Park.",
    "history_intro": "Savannah was laid out around public squares, starting in 1733. This walk visits three of them, each with its own story.",
    "planning": "The walk starts at a bus stop on Bay Street and finishes in Forsyth Park, about a mile south. Allow about 45 minutes.",
    "place": {
        "country": "US",
        "subdivision": "GA",
        "city": "Savannah"
    },
    "start": {
        "name": "Bay Street at Bull Street",
        "lat": 32.08082,
        "lng": -81.09118,
        "transit": true,
        "notes": "Downtown buses and the free shuttle stop here, beside City Hall."
    },
    "end": {
        "name": "Forsyth Park Fountain",
        "lat": 32.07013,
        "lng": -81.09521,
        "notes": "The fountain at the north end of Forsyth Park, with benches in the shade.",
        "getting_back": "Ride the free downtown shuttle north from the park to Bay Street, or walk back up Bull Street through the squares."
    },
    "stops": [
        {
            "name": "Johnson Square",
            "lat": 32.079942,
            "lng": -81.09161,
            "story": "Johnson Square was the first of Savannah's squares to be laid out, in 1733. It is named for Robert Johnson, a colonial governor of South Carolina and a friend of James Oglethorpe.\n\nThe obelisk in the middle honors General Nathanael Greene.",
            "quiz": [
                {
                    "question": "In what year was Johnson Square laid out?",
                    "choices": [
                        {
                            "text": "1733",
                            "correct": true
                        },
                        {
                            "text": "1812"
                        },
                        {
                            "text": "1900"
                        }
                    ]
                }
            ]
        },
        {
            "name": "Wright Square",
            "lat": 32.077882,
            "lng": -81.092368,
            "story": "Wright Square is named for James Wright, the last royal governor of the Province of Georgia. Tomochichi, a Creek leader and a trusted friend of James Oglethorpe, was buried here in 1739."
        },
        {
            "name": "Chippewa Square",
            "lat": 32.075839,
            "lng": -81.093136,
            "story": "Chippewa Square was laid out in 1815 and honors American soldiers killed at the Battle of Chippawa in the War of 1812. The opening bench scene of the movie Forrest Gump was filmed on its north side.",
            "restrooms": false,
            "stop_minutes": 15
        }
    ],
    "path": {
        "type": "LineString",
        "coordinates": [
            [-81.09118, 32.08082],
            [-81.09161, 32.079942],
            [-81.092368, 32.077882],
            [-81.093136, 32.075839],
            [-81.09395, 32.07385],
            [-81.09455, 32.07215],
            [-81.09521, 32.07013]
        ]
    }
}

Hikes built with a partner

Some hikes are built with a local historical society, museum or downtown association. If we've drafted one for your organization, we may send you a private preview link first, then offer the unpublished draft to your account. The offer appears on your Hike offers page, and nothing changes until you accept it. Once you do, you're the hike's creator and maintainer, the draft stays private, and you choose who it's credited to (you or one of your organizations) when you publish it. Photos keep their original credits.

Exports use the same format

When you export your data from Settings → Your data, each hike in the download is a file in this same format, with the hike's code and its photos as links. You can import it again here, as a new hike or to update the hike, or open it in any tool that reads the format. A hike built on the map can be bigger than the import limits above; trim it to fit before importing it.