Map Publishing

Map Publishing is everything that takes a map out of your organization. It covers four things: publishing itineraries and zones, the hosted embed that renders them in your pages, downloading an itinerary as a route file, and exporting it as a video. Your organization's agreement grants it. Map Studio, the editor, is a product of its own: an agreement can grant either without the other.

A studio offers what Map Publishing covers through its publish feature: Publish on an itinerary or a zone, downloading an itinerary's draft as a file, and the ways into an embed. Every member of an organization holding Map Studio and Map Publishing holds publish, whatever their role, and a studio hides all three without it rather than offer what the server refuses with 402. Publishing itself still asks a role that writes.

The map below is a live embed, rendered with the documentation demo key.

Publish an itinerary

An itinerary is edited as a draft and shown outside your organization as its published snapshot. The hosted embed, share links, and their tiles serve that snapshot alone, so an itinerary never published resolves to nothing on all of them. Publishing copies the draft into the next snapshot: Publish in the studio, or POST /v1/itineraries/{itinerary_id}/publication on the Map Studio API. The call acts as a member, so it takes the studio-embedded scope and a session token naming that member, and it needs Map Publishing beside Map Studio.

Your agreement sets how many itineraries you keep published at once, the published-itineraries limit: a first publish past it answers 402 coded LIMIT_REACHED. Taking an itinerary down, with DELETE on the same path, never needs Map Publishing.

To show a published itinerary to the people you choose rather than to every visitor of a page, mint a share link. It opens one itinerary, or one collection and everything filed in it, to whoever holds it, and its tiles are recorded apart and never counted.

While your organization does not hold Map Publishing, what it has published is withdrawn rather than refused: its hosted embed, its share links, and its published snapshots answer as if nothing were published, and they come back when the agreement does.

Publish a zone

A zone is published exactly as an itinerary is. It is edited as a draft, and outside your organization it is shown as its published snapshot: the name, description, level, mode, area, validity window, and source frozen when you published it. Publish on the zone in the studio, or POST /v1/zones/{zone_id}/publication on the Map Studio API, copies the draft into the next snapshot, under the same rules as an itinerary: the studio-embedded scope and a session token naming a member with a write role, Map Publishing beside Map Studio, no collaboration lock held on the zone, and If-Match to publish only the version you read. A zone owned by no organization is never published.

Your agreement sets how many zones you keep published at once, the published-zones limit, apart from published-itineraries. It allows none until your agreement names a number: a first publish past it answers 402 coded LIMIT_REACHED, and republishing a zone already live never does. Taking a zone down, with DELETE on the same path, frees its place at once and never needs Map Studio or Map Publishing.

A zone is public or private, as an itinerary is, and its privacy is a choice of its own, apart from its publication: the visibility control in the studio, or is_private when you create or update it. A new zone is private. Privacy is read from the draft and takes effect at once, without publishing again.

Who reads which version of a zone:

A zone has no share link, no route file, and no video of its own, and the hosted embed shows no zone alone: a collection embed draws the collection's published public zones, while your organization's with_collection_zones setting allows them. See collection_id.

Embed the map

The hosted embed serves the published map at https://app.mountaya.com/studio/embed, ready to drop into your page through an <iframe>. It renders your organization's published itineraries and collections, with a collection's published public zones, over Mountaya's terrain basemaps and environmental overlays, with the elevation profile and street view, and visitors explore it without editing it. Query parameters configure it, and a small postMessage API drives it at runtime.

The embed takes a publishable key with the publishing scope, in the iframe src, because a page cannot set the request headers of an iframe it frames. If your organization enforces short-lived session tokens, your page hands the embed one and renews it before it expires: the session script the embed wizard's snippet carries answers the embed's ask from your own endpoint, as renew the session token describes. A token put in the src as session_token is the secondary form, sent only until your page first answers. It loads only on a site listed in your organization's allowed domains. The tiles it draws are checked against publishing, so the key needs no tiles. Its overlay and content tiles are recorded as your organization's embedding usage, which counts toward its Tile API limit and allowance as your own clients' tiles do. The base map they are drawn on, its terrain style, source tiles, sprites, glyphs and elevation raster, is recorded under terrain and never counted: see what the Tile API counts. See authentication for the key and session model.

Download a route file

A published itinerary downloads as GPX, KML, KMZ, GeoJSON, FIT, TCX, or CSV. Visitors of an embed download it through its download control (with_download_control). Your own code calls GET /v1/itineraries/{itinerary_id}/export on the Map Studio API under the publishing scope: a publishable key alone, or a share token, exports the published snapshot. To hand a browser a link, the Data API's exportItinerary answers a signed URL that needs no credential of its own.

A key with a session token naming a member exports your organization's draft. A token naming nobody, the hosted embed's and a public viewer's among them, exports the published snapshot, as the key alone does. A draft leaves the studio as a file only while your organization holds Map Publishing, and is otherwise refused with 402.

Export a video

Map Studio records an itinerary as a video, with the elevation profile drawn into the frame. The video-export feature that opens it, and video-organization-modes for the custom format and the AI Director, are offered to a member of an organization that holds Map Publishing beside Map Studio. An Embedded Studio offers the same flow: see export a video.

Or build the map yourself

Mountaya publishes two ways to put its map in your product, and they are different products that share a vocabulary.

Map Publishing serves the hosted embed: the studio's map in an iframe, configured by URL and authenticated with a publishable key. No build step, no React, no bundle: you paste one tag and the whole published map arrives.

@mountaya/elements-react is the same map as components in your own tree: your layout, your controls, your state, your bundle. You compose the map view, the control stack and the panels yourself, and an elevation profile or a route table renders with no map at all.

Choose the iframe when you want a map. Choose the elements when you want to build one.

Next steps