Tutorial: Build your first route

Atlasemoji Docs

This is the shortest clean path from zero to something real: create a route, add chapters or stops, publish it, read the public manifest, open the embed, generate a static image, and turn it into a shareable postcard.

What you are making

By the end of this tutorial, you will have one route with public outputs that can be read in Atlasemoji, embedded on a website, rendered as a static map image, and shared as a postcard.

Back to developersSee a working embedSee a static route imageSee a postcard
What you’ll need

1. Create a route

Create the route shell first. This gives you the route document ID you will use while adding chapters or stops.

Tip: Save the returned route document ID. You will use it in the next steps as <ROUTE_ID>.
curl -X POST \
  -H "Authorization: Bearer <FIREBASE_ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Geronimo Trail Sample",
    "slug": "geronimo-trail-sample",
    "description": "A simple sample route for testing Atlasemoji APIs.",
    "emoji": "🗺️",
    "lang": "en"
  }' \
  "https://your-domain.com/api/me/routes"

2. Add your first waypoint

Add the first waypoint to the route. This can be an intro, a chapter, a stop, or any ordered point in the experience.

Tip: For story-style routes, keep wpIdx and order aligned unless you intentionally want something different.
curl -X POST \
  -H "Authorization: Bearer <FIREBASE_ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chapter 1: Departure",
    "notes": "<p>The journey begins here.</p>",
    "emoji": "👣",
    "lat": 47.6062,
    "lng": -122.3321,
    "lang": "en",
    "wpIdx": 1,
    "order": 1,
    "kind": "storypoint",
    "takenAt": "2026-03-08T12:00:00.000Z"
  }' \
  "https://your-domain.com/api/me/routes/<ROUTE_ID>/waypoints"

3. Add more route waypoints

Routes are flexible. You can make a short 3-stop route, a classic 10-chapter story, or a much longer guided sequence.

Tip: You are not locked to 10 waypoints. Publish whatever length makes sense for the route.
curl -X POST \
  -H "Authorization: Bearer <FIREBASE_ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chapter 2: Canyon Pass",
    "notes": "<p>Second stop or chapter.</p>",
    "emoji": "🏜️",
    "lat": 32.22,
    "lng": -109.449,
    "lang": "en",
    "wpIdx": 2,
    "order": 2,
    "kind": "storypoint"
  }' \
  "https://your-domain.com/api/me/routes/<ROUTE_ID>/waypoints"

4. Review the route waypoints

Before publishing, inspect the route waypoints and make sure titles, order, language, kind, and coordinates all look right.

curl \
  -H "Authorization: Bearer <FIREBASE_ID_TOKEN>" \
  "https://your-domain.com/api/me/routes/<ROUTE_ID>/waypoints"

5. Publish the route

Publishing computes the public routeId, bounds, waypoint count, and overview polyline. This is the moment the route becomes readable and embeddable.

Tip: The publish response gives you the public routeId. That is the ID used by the read, embed, postcard, and static image surfaces.
curl -X POST \
  -H "Authorization: Bearer <FIREBASE_ID_TOKEN>" \
  "https://your-domain.com/api/me/routes/<ROUTE_ID>/publish"

6. Read the canonical public manifest

Once published, use the public route contract. This is the same manifest that powers Atlasemoji Read mode.

curl \
  "https://your-domain.com/api/routes/<PUBLISHED_ROUTE_ID>?lang=en"

7. Open the embed page

The embed page is a visual proof that your published route is usable outside the core app.

https://your-domain.com/embed/<PUBLISHED_ROUTE_ID>?lang=en

8. Generate a static route image

Use the static image endpoint when you need a preview image for docs, blogs, link cards, newsletters, or classroom material.

https://your-domain.com/api/embed/<PUBLISHED_ROUTE_ID>/static?lang=en&width=1200&height=630

9. Share it as a postcard

Once the route is public, you can also turn it into a postcard-style share surface for social sharing, lightweight previews, and visual storytelling.

Tip: This is a good public-facing share format when you want something more narrative than raw JSON and lighter than full app navigation.
https://your-domain.com/postcard/<PUBLISHED_ROUTE_ID>?lang=en

What the published result looks like

After publishing, your route becomes a canonical public manifest. That same manifest can power Read mode, embeds, postcards, static maps, and external apps.

{
  "ok": true,
  "routeId": "route-geronimo-trail-sample",
  "slug": "geronimo-trail-sample",
  "lang": "en",
  "requestedLang": "en",
  "resolvedLang": "en",
  "title": "Geronimo Trail Sample",
  "overviewPolyline": "...",
  "bounds": {
    "minLat": 32.22,
    "maxLat": 47.6062,
    "minLng": -122.3321,
    "maxLng": -109.449
  },
  "chapterCount": 2,
  "waypoints": [
    {
      "wpIdx": 1,
      "title": "Chapter 1: Departure"
    },
    {
      "wpIdx": 2,
      "title": "Chapter 2: Canyon Pass"
    }
  ]
}

What to build next

    Atlasemoji