Get started
Reference

MountayaMap

MountayaMap

MountayaMap is a Mountaya map on MapLibre: a container and a client draw a base map from the layers manifest, and every layer added afterwards lands at its rank in LayerRank.

new MountayaMap(options)

Builds the renderer in options.container and asks for the base map: the style given, or the catalogue terrain terrain names (the manifest's first by default).

new MountayaMap(options)

options

MountayaMapOptions

required

MountayaMapOptions is everything new MountayaMap(...) takes.

Properties

PropertyTypeSummary
rawRawMapThe MapLibre map underneath.
geolocationGeolocationSeamWhere a device fix comes from.
iconsIconProviderThe glyph set markers draw from.
eventsMapEventsThe map's listeners, typed by MapLibre's own events, and the deferral to the style a base-map switch brings in (MapEvents).

Methods

setItinerary

Draws one itinerary, and frames it when fit asks. Replaces whichever was drawn before; null clears.

setItinerary(itinerary, options?)

itinerary

Renderable

required

The itinerary's id, a specification already held, or null to clear.

options

ItineraryDrawOptions

default: {}

fit frames the itinerary once it is drawn, and signal withdraws the call.

Returns Promise<{ readonly drawn: boolean }>: Whether this call's itinerary is the one drawn.

drawn

boolean

required

setCollection

Draws one collection: every itinerary and zone it holds. Replaces whichever was drawn before; null clears.

setCollection(collection, options?)

collection

Renderable

required

The collection's id, a specification already held, or null to clear.

options

CollectionDrawOptions

default: {}

fit frames the collection once it is drawn, and signal withdraws the call.

Returns Promise<{ readonly drawn: boolean }>: Whether this call's collection is the one drawn.

drawn

boolean

required

clearItinerary

clearItinerary, clearCollection and clearOverlay are the explicit clears, one per set.

clearItinerary()

clearCollection

Clears the collection drawn, as setCollection(null) does.

clearCollection()

clearOverlay

Clears the classic overlay drawn, as setOverlay(null) does.

clearOverlay()

setItineraries

Toggles the aggregate itineraries layer: the itineraries of the credential's own scope, every one of its organization's under a key or a share token, and a signed-in person's personal space under their session. A map that follows another studio scope reads the layers catalog for it instead (setLayersOrganization).

setItineraries(on)

on

boolean

required

setZones

Toggles the zones layer: the zones of the credential's own scope, as setItineraries reads it.

setZones(on)

on

boolean

required

setTerrain

Switches the base map, by terrain slug.

setTerrain(slug)

slug

string | null

required

The terrain's slug as the manifest spells it, or null for the manifest's first terrain.

setStyle

Swaps the base style for one you name, keeping everything drawn on top of it.

setStyle(style, options?)

style

StyleSpecification | string

required
options

{ readonly transformStyle?: TransformStyleFunction | undefined }

default: {}

getTerrain

The slug of the catalogue terrain the base map is on, or null when it is on none: before the first terrain is found in the manifest, and under a style of the host's own (the style option, setStyle).

getTerrain()

Returns string | null: The terrain's slug as the manifest spells it, or null.

setTerrainVariant

Switches the base map to the light or the dark variant of its catalogue terrain, apart from any colour scheme of the page around it.

setTerrainVariant(variant)

variant

TerrainVariant

required

"light" or "dark".

getTerrainVariant

The variant of a catalogue terrain the map draws: the variant of the terrain getTerrain names, on its way or shown, and otherwise the variant the next setTerrain draws in, which is the one the host asked for last. "light" unless the host asked for dark.

getTerrainVariant()

Returns TerrainVariant

setOverlay

Draws one classic overlay, by slug. Replaces whichever was drawn before; null clears.

setOverlay(slug)

slug

string | null

required

setOverlaySpecification

Draws one classic overlay you already hold, without reading the manifest.

setOverlaySpecification(overlay, options?)

overlay

Overlay

required
options

MountOptions

default: {}

addEnrichment

Adds one enrichment overlay on top of whatever is already drawn.

addEnrichment(slug)

slug

string

required

addEnrichmentSpecification

Adds one enrichment overlay you already hold, without reading the manifest.

addEnrichmentSpecification(overlay, options?)

overlay

Overlay

required

Its fields are listed under setOverlaySpecification.

options

MountOptions

default: {}

Its fields are listed under setOverlaySpecification.

removeEnrichment

Removes one enrichment, by the slug addEnrichment was handed, and an addEnrichment of it still reading the manifest draws nothing. A slug not drawn changes nothing.

removeEnrichment(slug)

slug

string

required

clearEnrichments

Removes every enrichment, the ones still being found in the manifest included.

clearEnrichments()

getEnrichments

The enrichment slugs currently drawn, in the order they were added.

getEnrichments()

Returns readonly string[]: The slugs, as one frozen array until the next displaychange.

setSpecification

Draws a specification you already hold, under a name of your choosing.

setSpecification(name, specification, options?)

name

string

required
specification

TileSpecification

required
options

MountOptions

default: {}

Its fields are listed under setOverlaySpecification.

removeSpecification

Removes the specification drawn under name. A name holding nothing is a no-op.

removeSpecification(name)

name

string

required

clearSpecifications

Removes every specification mounted by name, leaving this package's own slots drawn.

clearSpecifications()

getSpecifications

The names currently drawn, in the order they were mounted.

getSpecifications()

Returns readonly string[]: The names, as one frozen array until the next displaychange.

addLayer

Adds a layer of your own at a Mountaya rank, so it lands where that kind of layer belongs.

addLayer(layer, rank)

layer

AddLayerObject

required
rank

LayerRank

required

removeLayer

Removes a layer added by addLayer, and forgets its rank and visibility.

removeLayer(id)

id

string

required

setStreetviewCoverage

Shows or hides Google's Street View coverage raster: where a panorama exists.

setStreetviewCoverage(visible, paint?)

visible

boolean

required
paint

RasterPaint

default: {}

addDirections

Draws routed directions between waypoints.

addDirections(input, options?)

input

DirectionsInput | DirectionsResult

required
options

DrawOptions

default: {}

Returns Promise<AnalysisHandle<DirectionsResult>>

id

AnalysisId

required
result

Result

required

editDirections

Re-runs one directions result with patch merged onto the input it was drawn from. An empty patch restyles it from the result held, asking nothing. A member the patch or the options state as undefined leaves the one held.

editDirections(id, patch, options?)

id

AnalysisId

required
patch

Partial<DirectionsInput>

required
options

DrawOptions

default: {}

Its fields are listed under addDirections.

Returns Promise<DirectionsResult>

routes

Array<DirectionsRoute>

required

List of computed routes between the provided waypoints.

removeDirections

Removes one result, by the id addDirections answered, and cancels its query while it is in flight. An id not drawn changes nothing.

removeDirections(id)

id

AnalysisId

required

clearDirections

Removes every directions result, and cancels the addDirections calls still waiting on their query: each rejects with the client's AbortError and draws nothing.

clearDirections()

addSuggestions

Draws a set of suggested itineraries: the first solid, the rest dashed alternatives.

addSuggestions(input, options?)

input

SuggestionsInput | SuggestionsResult

required
options

SuggestionDrawOptions

default: {}

Returns Promise<AnalysisHandle<SuggestionsResult>>

Its fields are listed under addDirections.

editSuggestions

Re-runs or restyles one suggestion set.

editSuggestions(id, patch?, options?)

id

AnalysisId

required
patch

Partial<SuggestionsInput>

default: {}

Its fields are listed under editDirections.

options

SuggestionDrawOptions

default: {}

Its fields are listed under addSuggestions.

Returns Promise<SuggestionsResult>

routes

Array<SuggestionRoute>

required

Suggested route candidates: pinned seeds first, in the order given, then fresh candidates nearest the target distance first, or nearest the distance and ascent targets combined when ascent is positive. Can hold fewer routes than candidates.

removeSuggestions

Removes one result, by the id addSuggestions answered, and cancels its query while it is in flight. An id not drawn changes nothing.

removeSuggestions(id)

id

AnalysisId

required

clearSuggestions

Removes every suggestion set, and cancels the addSuggestions calls still waiting on their query: each rejects with the client's AbortError and draws nothing.

clearSuggestions()

addIsochrones

Draws reachability bands around one or more origins.

addIsochrones(input, options?)

input

IsochronesInput | IsochronesResult

required
options

DrawOptions

default: {}

Its fields are listed under addDirections.

Returns Promise<AnalysisHandle<IsochronesResult>>

Its fields are listed under addDirections.

editIsochrones

Re-runs one isochrone set with patch merged onto the input it was drawn from. An empty patch restyles it from the result held, asking nothing. A member the patch or the options state as undefined leaves the one held.

editIsochrones(id, patch, options?)

id

AnalysisId

required
patch

Partial<IsochronesInput>

required

Its fields are listed under editDirections.

options

DrawOptions

default: {}

Its fields are listed under addDirections.

Returns Promise<IsochronesResult>

isochrones

Array<Isochrone>

required

List of computed isochrones: one per location and range value, in the order the routing engine returns them. Read each one's value rather than relying on its position.

removeIsochrones

Removes one result, by the id addIsochrones answered, and cancels its query while it is in flight. An id not drawn changes nothing.

removeIsochrones(id)

id

AnalysisId

required

clearIsochrones

Removes every isochrone set, and cancels the addIsochrones calls still waiting on their query: each rejects with the client's AbortError and draws nothing.

clearIsochrones()

addPlaces

Draws geocoding hits as labelled points.

addPlaces(input, options?)

input

GeocodeInput | GeocodeResult

required
options

DrawOptions

default: {}

Its fields are listed under addDirections.

Returns Promise<AnalysisHandle<GeocodeResult>>

Its fields are listed under addDirections.

editPlaces

Re-runs one place search with patch merged onto the input it was drawn from. An empty patch restyles it from the result held, asking nothing. A member the patch or the options state as undefined leaves the one held.

editPlaces(id, patch, options?)

id

AnalysisId

required
patch

Partial<GeocodeInput>

required

Its fields are listed under editDirections.

options

DrawOptions

default: {}

Its fields are listed under addDirections.

Returns Promise<GeocodeResult>

count

Scalars["Int"]["output"]

required

Number of places returned: the length of places, at most limit.

places

Array<Place>

required

List of named places ordered by relevance.

removePlaces

Removes one result, by the id addPlaces answered, and cancels its query while it is in flight. An id not drawn changes nothing.

removePlaces(id)

id

AnalysisId

required

clearPlaces

Removes every place search result, and cancels the addPlaces calls still waiting on their query: each rejects with the client's AbortError and draws nothing.

clearPlaces()

addMatrix

Draws a time-distance matrix as connectors between its locations.

addMatrix(input, options?)

input

MatrixInput

required

The matrix to solve: its locations, and the metrics to weigh each pair by.

options

MatrixDrawOptions

default: {}

fit frames the matrix once it is drawn, and result is a result already held for input, drawn with no query.

Returns Promise<AnalysisHandle<MatrixResult>>: The id the matrix is drawn under, and its result: the client's answer, or options.result as it was handed over.

Its fields are listed under addDirections.

editMatrix

Re-runs one matrix with patch merged onto the input it was drawn from. An empty patch restyles it from the result held, asking nothing. A member the patch or the options state as undefined leaves the one held.

editMatrix(id, patch, options?)

id

AnalysisId

required
patch

Partial<MatrixInput>

required

Its fields are listed under editDirections.

options

DrawOptions

default: {}

Its fields are listed under addDirections.

Returns Promise<MatrixResult>

distances

Maybe<Array<Array<Maybe<Scalars["Float"]["output"]>>>>

Distance grid in meters, one row per source and one column per destination: the routing engine's own figures, with no geometry returned to measure them against. Null inner values indicate unreachable pairs. Only present when DISTANCE metric is requested.

durations

Maybe<Array<Array<Maybe<Scalars["Float"]["output"]>>>>

Duration grid in seconds, one row per source and one column per destination. These are the routing engine's own estimates: they take no speed and do not use the terrain-aware model behind duration on directions, suggestions and analyzeGeometry, so they are not comparable with it. Null inner values indicate unreachable pairs. Only present when DURATION metric is requested.

removeMatrix

Removes one result, by the id addMatrix answered, and cancels its query while it is in flight. An id not drawn changes nothing.

removeMatrix(id)

id

AnalysisId

required

clearMatrix

Removes every matrix, and cancels the addMatrix calls still waiting on their query: each rejects with the client's AbortError and draws nothing.

clearMatrix()

setPointsOfInterest

Draws the result of a points-of-interest query. One at a time, so this replaces.

setPointsOfInterest(input, options?)

input

PoisInput | PoisResult

required
options

DrawOptions

default: {}

Its fields are listed under addDirections.

Returns Promise<PoisResult>

count

Scalars["Int"]["output"]

required

Number of POIs returned: the length of pois, at most limit.

pois

Array<Poi>

required

List of POIs ordered by relevance. A buffered area does not reorder them by distance: read each one's distanceMeters.

editPointsOfInterest

Re-runs the POI query with patch merged onto the input it was drawn from. An empty patch restyles it from the result held, asking nothing. A member the patch or the options state as undefined leaves the one held.

editPointsOfInterest(patch, options?)

patch

Partial<PoisInput>

required

Its fields are listed under editDirections.

options

DrawOptions

default: {}

Its fields are listed under addDirections.

Returns Promise<PoisResult>

Its fields are listed under setPointsOfInterest.

clearPointsOfInterest

Removes the points of interest drawn, and cancels their query while it is in flight.

clearPointsOfInterest()

setPreview

Draws one unsaved geometry, an itinerary being planned. null clears.

setPreview(geometry, options?)

geometry

Geometry | null

required
options

{ readonly color?: string | undefined }

default: {}

editPreview

Changes the preview's geometry, its colour, or both, keeping whatever is not named.

editPreview(patch)

patch

{ readonly geometry?: Geometry | undefined; readonly color?: string | undefined }

required

clearPreview

Clears the unsaved geometry setPreview draws, as setPreview(null) does.

clearPreview()

setHighlight

Draws one highlighted feature, a search result. null clears.

setHighlight(feature, options?)

feature

Feature | null

required
options

{ readonly color?: string | undefined }

default: {}

editHighlight

Changes the highlighted feature, its colour, or both, keeping whatever is not named. A new colour reaches the drawn layers at once, with nothing rebuilt.

editHighlight(patch)

patch

{ readonly feature?: Feature | undefined; readonly color?: string | undefined }

required

clearHighlight

Clears the geometry setHighlight draws, as setHighlight(null) does.

clearHighlight()

setEmphasis

Lights one stretch of what is already drawn: the leg a reader is pointing at.

setEmphasis(feature, options?)

feature

Feature | null

required
options

{ readonly color?: string | undefined }

default: {}

clearEmphasis

Clears the geometry setEmphasis draws, as setEmphasis(null) does.

clearEmphasis()

addMarker

Pins a marker. An id already in use is replaced, so this is safe to call on every render.

addMarker(marker)

marker

MarkerOptions

required

editMarker

Changes one marker, keeping whatever the patch does not name.

editMarker(id, patch)

id

string

required
patch

Partial<Omit<MarkerOptions, "id">>

required

Its fields are listed under editDirections.

removeMarker

Takes the marker pinned under id off the map and forgets what it was built from, so a later editMarker of that id throws. An id nothing is pinned under is a no-op.

removeMarker(id)

id

string

required

clearMarkers

Removes every marker addMarker placed.

clearMarkers()

getCamera

The camera as it stands: its centre, zoom, bearing and pitch.

getCamera()

Returns Camera

center

[number, number]

required
zoom

number

required
bearing

number

required
pitch

number

required

getZoomLimits

The zoom window the camera is held to: the lowest zoom it may reach and the highest.

getZoomLimits()

Returns { readonly max: number; readonly min: number }

max

number

required
min

number

required

jumpTo

Moves the camera immediately, with no animation.

jumpTo(pose)

pose

CameraPose

required

flyTo

Moves the camera with the curved, zoom-out-and-in flight MapLibre calls a fly.

flyTo(pose)

pose

CameraPose

required

Its fields are listed under jumpTo.

easeTo

Moves the camera with a straight ease. The default for a programmatic move.

easeTo(pose)

pose

CameraPose

required

Its fields are listed under jumpTo.

fitBounds

Moves the camera to frame a box, with the padding, zoom ceiling and duration options give. A member left out, or stated as undefined, takes MapLibre's own default.

fitBounds(bounds, options?)

bounds

BoundingBox | LngLatBoundsLike

required
options

FitBoundsOptions

default: {}

easeIntoZoomRange

Eases the camera into the zoom range a specification paints over.

easeIntoZoomRange(target)

target

TileSpecification | ZoomRange

required

zoomIn

Eases the camera one zoom level in, within the zoom window the map holds.

zoomIn()

zoomOut

Eases the camera one zoom level out, within the zoom window the map holds.

zoomOut()

resetNorth

Rotates back to north, and levels the pitch: what a compass control means by reset.

resetNorth()

setConstraints

Sets the limits the camera may not leave: a zoom floor, a zoom ceiling and a pan lock. A member left out keeps its current limit, and a member of null releases it: a maxBounds of null lifts the lock, and a zoom limit of null goes back to the one a map is built with when it is given none, a floor of -2 and a ceiling of 22.

setConstraints(constraints)

constraints

CameraConstraints

required

setLanguage

Sets the language labels are drawn in.

setLanguage(language)

language

string

required

getLanguage

The language labels are drawn in: the one setLanguage or the language option asked for, as the tiles carry it.

getLanguage()

Returns MapLanguage

project

The pixel a coordinate is drawn at, from the canvas's top-left corner. A destroyed map has no projection, and answers [NaN, NaN].

project(lngLat)

lngLat

[number, number]

required

Returns [number, number]

unproject

The coordinate drawn at a pixel of the canvas. A destroyed map has no projection, and answers [NaN, NaN].

unproject(point)

point

[number, number]

required

Returns [number, number]

featuresAt

The features this map drew at a screen point.

featuresAt(point)

point

[number, number]

required

Returns Feature[]

poisAt

The POI features rendered at a screen point.

poisAt(point)

point

[number, number]

required

Returns Feature[]

zonesAt

The zone features rendered at a screen point.

zonesAt(point)

point

[number, number]

required

Returns Feature[]

itinerariesAt

The itinerary features (routed lines and waypoints) rendered at a screen point.

itinerariesAt(point)

point

[number, number]

required

Returns Feature[]

elevationAt

Ground elevation at a coordinate, in meters.

elevationAt(lngLat)

lngLat

[number, number]

required

Returns Promise<number | null>

Full-text search across places, POIs, ways and the caller's own itineraries, collections and zones.

search(input, options?)

input

SearchInput

required
options

{ readonly signal?: AbortSignal | undefined }

default: {}

Returns Promise<SearchResult>

collections

Maybe<CollectionsResult>

Collections section. Null when the collections target was disabled or its branch errored.

errors

Array<SearchTargetError>

required

Graceful-degradation entries: one per target whose branch failed, or answered only in part because of a failure on Mountaya's side. Empty when every enabled branch succeeded.

itineraries

Maybe<ItinerariesResult>

Itineraries section. Null when the itineraries target was disabled or its branch errored.

language

Language

required

Language the place, POI and way names were returned in: the requested language when it is EN or FR, and EN otherwise, including when none was given.

places

Maybe<GeocodeResult>

Geocoded places section. Null when the places target was disabled or its branch errored.

pois

Maybe<PoisResult>

Points-of-interest section. Null when the pois target was disabled or its branch errored.

query

Scalars["String"]["output"]

required

Echo of the input query.

targets

SearchTargets

required

Echo of the per-target enable flags carried by the input.

ways

Maybe<WaysResult>

Named-ways section. Null when the ways target was disabled or its branch errored.

zones

Maybe<ZonesResult>

Zones section. Null when the zones target was disabled or its branch errored.

locate

locate(options?)

options

GeolocationFixOptions

default: {}

Returns Promise<[number, number]>

setLayerVisibility

setLayerVisibility shows or hides one layer of a drawn overlay, by its manifest id.

setLayerVisibility(layerId, visible)

layerId

string

required
visible

boolean

required

isLayerVisible

isLayerVisible reports whether a layer is shown, that is not hidden by setLayerVisibility.

isLayerVisible(layerId)

layerId

string

required

Returns boolean

drawnLayerKeys

The manifest concept keys currently drawn, in the order their layers were mounted.

drawnLayerKeys(rank?)

rank

LayerRank

Returns readonly string[]: The keys, as one frozen array per rank until the next displaychange.

layerIdsForKey

The ids of the drawn layers carrying one manifest key. Empty for a key nothing draws.

layerIdsForKey(key)

key

string

required

Returns readonly string[]: The ids, as one frozen array per key until the next displaychange.

setKeyVisibility

Shows or hides every layer drawing one manifest concept.

setKeyVisibility(key, visible)

key

string

required
visible

boolean

required

isKeyVisible

Whether a concept is shown. A key drawing nothing reads as visible, matching isLayerVisible: nothing has been hidden, so nothing is.

isKeyVisible(key)

key

string

required

Returns boolean

loadLayers

Loads the layers manifest: every terrain, overlay and enrichment this credential may draw in the studio scope setLayersOrganization names. getLayers answers the one already loaded, with no read.

loadLayers()

Returns Promise<Layers>

elevation

components["schemas"]["Elevation"]

required
itineraries

components["schemas"]["Overlay"]

required
overlays

components["schemas"]["CategoryOverlays"][]

required
terrains

components["schemas"]["Terrain"][]

required
zones

components["schemas"]["Overlay"]

required

getLayers

The layers manifest if it has already resolved, and undefined if it has not.

getLayers()

Returns Layers | undefined

Its fields are listed under loadLayers.

setLayersOrganization

Names the studio scope the layers manifest is read for: an organization, sent as organization_id, or null for the read that names none.

setLayersOrganization(organizationId)

organizationId

string | null

required

The organization whose scope the manifest is read for, or null for the read that names none.

whenReady

Resolves once the map is ready to take sources and layers, and at once for a destroyed map, which is waiting on no style.

whenReady()

on

Subscribes to a map event. Returns the unsubscribe, so a caller never has to keep the handler around to detach it, the mistake that leaks listeners in every React codebase.

on<E>(event, handler)

event

E

required

The event, such as "moveend", "click" or "styleload".

handler

(payload: MountayaMapEvents[E]) => void

required

Called with the event's payload.

Returns Unsubscribe: An unsubscribe that detaches this handler and no other.

destroy

Tears the map down. Idempotent: calling it twice is not an error.

destroy()

Events

Subscribe with map.on(event, handler), which returns the function that unsubscribes.

EventPayloadSummary
click{ readonly lngLat: [number, number]; readonly point: [number, number] }A click anywhere on the map that no edit in progress took.
moveCameraThe camera as it changes: continuously through a pan, zoom, rotate or pitch, and once per rendered frame for as long as the gesture or the animation lasts.
moveendCameraThe camera settled after a pan, zoom, rotate or pitch.
zoomlimitschange{ readonly max: number; readonly min: number }The zoom window changed: the lowest or the highest zoom the camera may reach, as getZoomLimits now answers it.
featureclick{ readonly lngLat: [number, number]; readonly features: readonly Feature[] }A click that landed on one of the map's own features, told as click is and under the same rule, its longitude within [-180, 180].
featurehover{ readonly lngLat: [number, number]; readonly features: readonly Feature[] }The pointer moved over the map: features holds the itinerary's features under it, routed lines and waypoints, topmost first, and is empty while the pointer is off them and as it leaves the canvas.
contextmenu{ readonly lngLat: [number, number]; readonly point: [number, number] }A right-click, or a long press, anywhere on the map that no edit in progress took.
accessrequired{ readonly status: number; readonly url: string }The API refused one of the map's own requests for want of access: a 401, a 402 or a 403.
displaychangeundefinedWhat the map draws from its tile slots, or shows of it, changed: an itinerary, a collection, an overlay, an enrichment, a named specification or a toggle was asked for, replaced or cleared; a layer of the caller's own was added, removed or placed at another rank; or a layer or a key was hidden or shown.
layerschangeundefinedWhat getLayers answers changed: a read of the layers manifest landed, or setLayersOrganization moved the studio scope and dropped the manifest held, which getLayers then answers as undefined until the new scope's read lands.
styleloadundefinedA style finished loading: the one the map is built with, the one each base-map switch brings in, and the one the map had as it returns with a lost WebGL context.
error{ readonly error: Error }A failure with no call of yours on the stack to reject: an error MapLibre reported (a style that does not parse, a tile the server failed on), the base map the constructor asked for not arriving (the layers manifest unreachable, a terrain it does not list), or the canvas losing its WebGL context.