Zones
Areas with something to say about them: an avalanche bulletin, a closure, a permit boundary. A zone carries a severity level and an optional validity window, which the zone tiles filter on when asked for an instant, so a warning that has expired drops off such a map without anybody deleting it. A zone is published as an itinerary is, and what is drawn outside the organization is its last publication.
A geographic annotation drawn on the map, such as a hazard zone, an information marker, or a custom area.
created_atstring (date-time)
Timestamp of the zone's creation.
created_byobject
The user who created the zone. It is the author rather than the last editor, and it does not move when another member edits the zone.
descriptionstring | null
Free-text description of the zone. Null when it has none.
end_atstring (date-time) | null
End of the temporal validity window. After this time the zone is not in force. Null when the zone has no expiration.
etagstring
The version of everything a read of this zone returns, the one the ETag of that read carries, opaque and compared whole. It moves on every write to the zone and on a publish or unpublish, so a client holding it knows whether anything it shows is stale. A draft read and a read served the published snapshot carry different tags. Send it as If-Match to make patchZone, deleteZone, postZonePublication or deleteZonePublication conditional.
geojsonobject
The zone's area, as a GeoJSON Feature whose id is the zone id. On a sourced zone this is the polygon the source computed, not the inputs that produced it; source carries those.
has_unpublished_changesboolean
Whether the draft has been edited since the last publish, so the public surfaces are serving something older than what the studio shows. Derived server-side by comparing the zone's updated_at against its latest publication; read-only and never accepted as an input. Always false while status is draft.
idstring (uuid)
Unique identifier of the zone.
is_privateboolean
Whether the zone is private. A private zone is reached only with the key of the organization that owns it, so a private personal zone, owned by no organization, is reached by no key. A public zone is readable by id, read-only, by any publishable key, as last published, and it is listed only in its own organization's listings. A collection's share token reaches the zones that collection holds whatever this says. Public never grants editing, which takes a write role in the owning organization. Privacy is read from the draft, so a change takes effect at once rather than at the next publish.
levelstring
One of: info, resolved, warning, danger
How serious the zone is, which is what a renderer picks its styling from. It carries no access meaning: a zone is visible or not by is_private and its publication, never by its level.
modestring
One of: polygon, circle, sensor, sector, freehand
How the zone's area was drawn or computed. A zone computed from source is polygon.
namestring
Display name of the zone.
organization_idstring (uuid) | null
Identifier of the organization that owns this zone. Null for a personal zone, made from an individual account and owned by no organization.
published_atstring (date-time) | null
Timestamp of the zone's live publication, or null when it has none: when it has never been published, or has been taken down. Derived server-side: publishing is the only thing that sets it, taking the zone down clears it, and it is never accepted as an input.
revisioninteger (int32)
Revision number of the zone, incremented by every patchZone, even one that changes nothing. Publishing and unpublishing leave it where it is. On a read served the published snapshot it is the publication number instead. A consumer holding an older copy compares it with the revision a change frame carries; no request takes it.
sourceZoneSource | null
Provenance of the zone's geometry. Populated for a computed zone and null for a zone drawn by hand. The polygon is computed from these inputs on create and recomputed only by a patchZone that sends source. A patchZone sending geojson replaces the area and clears this, one sending source: null clears it and keeps the area, and every other write keeps both.
start_atstring (date-time) | null
Start of the temporal validity window. Before this time the zone is not in force. Null when the zone is in force at once.
statusstring
One of: draft, published
Whether the zone is published right now, that is whether it has a live publication. Derived server-side; read-only and never accepted as an input. Taking a zone down returns it to draft, although its publication number is kept, so a later publish takes the next one. Note this is independent of is_private: a draft is invisible on the public surfaces however public its privacy setting says it is.
updated_atstring (date-time)
When the zone's latest revision was written. Every patchZone moves it, even one that changes nothing. Always present: it equals created_at until the first patch.
/v1/zonesReturns the zones of the key's organization, one page at a time. A zone belongs to the organization that owns it, not to the user who drew it, so this is the listing every member shares.
Query parameters
cursorstring
in query
Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.
limitinteger (int32)
in query
default: 50
How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.
organization_idstring (uuid)
in query
The organization to list for. It can only be the key's organization, which is also what the listing covers when this is omitted; any other identifier is a 403, whether or not it exists. A personal resource, owned by no organization, is never listed under a key.
statusstring
in query
One of: draft, published
Lists only the zones in this publication state: published those with a live publication, draft those with none. Omitted, both are listed. A key alone is served published zones only, and so is a key with a session token naming nobody, so draft lists nothing under either.
is_privateboolean
in query
true lists only private items and false only public ones; omitted, both are listed. It narrows and never widens: what a credential lists is still decided by the read tiers in this document's introduction, so a key without a session token naming a member lists no private item whatever this says.
levelstring
in query
One of: info, resolved, warning, danger
Lists only the zones of this level.
modestring
in query
One of: polygon, circle, sensor, sector, freehand
Lists only the zones drawn or computed this way. A zone computed from a source is polygon.
active_atstring (date-time)
in query
Lists only the zones in force at this instant: those whose validity window contains it, with a start_at at or before it, or none, and an end_at at or after it, or none. Send the current time to list what applies now.
updated_sincestring (date-time)
in query
Lists only what changed at or after this instant, compared with each item's updated_at. With sort=updated_at, it is how a client picks up what changed since its last read without walking the whole listing.
qstring
in query
Lists only the items whose name contains this text, compared without regard to case. 1 to 100 characters; leading and trailing whitespace is ignored.
sortstring
in query
default: -updated_at
One of: -updated_at, updated_at, -created_at, created_at, name, -name
The order the listing is served in, by one key: updated_at, created_at or name, ascending as written and descending with a leading -. -updated_at when omitted, so the zone changed last comes first. Ties break on id, so no two items share a place in the order, and a page boundary never falls between two that compare equal.
Response 200
One page of the zones this credential reaches, in the order sort names. extensions.metadata.pagination.next_cursor asks for the next page, and is null on the last.
extensionsobject
The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at, and the next_cursor that asks for the next one, null on the last page.
dataarray of Zone
See the Zone object.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
Creates a zone in the key's organization: a named area drawn by hand as a single Polygon, or computed from a source. Any geometry other than a Polygon, a null geometry included, is a 400 naming geojson.geometry, and so is a Polygon whose outline one meridian or one parallel crosses more than 512 times, every ring counted, which is too intricate to be stored, and one that is not a valid polygon, in degrees as sent or once projected to Web Mercator, as a map draws it: a ring that crosses itself or another ring, a ring that touches itself, or a hole outside its shell. A straight edge in degrees is drawn as another line on a map, so an outline valid in degrees can cross itself once projected, and is refused. An area computed from a source held to none of these, or of more than 10,000 positions, is a 400 naming source: change its location or range, or draw the zone. An end_at earlier than start_at is a 400 naming end_at.
Webhook events zone.created, recorded by the task zone.create.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
The new zone: its level, its validity window, and either the polygon to store as sent, less any altitude and feature properties, or the source to compute one from. Send exactly one of the two.
descriptionstring
in body
Free-text description of the zone, at most 100 characters as sent, stored with leading and trailing whitespace trimmed. Omit it, or send one that trims to nothing, to create the zone without one.
end_atstring (date-time)
in body
End of the temporal validity window. Optional and not nullable: omit it for a zone with no expiration. One earlier than start_at is a 400 naming end_at.
geojsonobject
in body
The area of a zone drawn by hand. Provide exactly one of geojson or source. An id on the feature becomes the zone's id; one that another zone already has is a 409.
is_privateboolean
in body
Whether the zone is private. A private zone is reached only with the key of the organization that owns it, so a private personal zone, owned by no organization, is reached by no key. A public zone is readable by id, read-only, by any publishable key, as last published, and it is listed only in its own organization's listings. A collection's share token reaches the zones that collection holds whatever this says. Public never grants editing, which takes a write role in the owning organization. Privacy is read from the draft, so a change takes effect at once rather than at the next publish.
levelstring
in body
One of: info, resolved, warning, danger
How serious the zone is, which is what a renderer picks its styling from. It carries no access meaning: a zone is visible or not by is_private and its publication, never by its level.
modestring
in body
One of: polygon, circle, sensor, sector, freehand
How the zone's area is drawn or computed. A zone given a source must be polygon; any other mode beside a source is a 400.
namestring
in body
Display name of the zone, at most 30 characters as sent, and at least 2 once leading and trailing whitespace is trimmed. Refused with a 409 when another zone in the organization already carries it. Names are compared exactly after trimming, case included, so Alps and alps are two different names. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.
organization_idstring (uuid)
in body
Identifier of the organization that will own the zone. It must be the key's organization; omitted, it is that organization.
sourceobject
in body
Provenance inputs for a computed zone. Provide exactly one of geojson or source; when source is given the zone's polygon is computed from these inputs and the source is kept, so the zone can be refreshed by sending it again on an update. An area computed from the source is held to every rule a drawn one is, its 10,000 positions included, and one that breaks any is a 400 naming source, and nothing is created.
start_atstring (date-time)
in body
Start of the temporal validity window. Optional and not nullable: omit it for a zone that is active immediately.
Response 201
The zone as created, with its polygon either stored as sent, less any altitude and feature properties, or computed from the source. Location names it, /v1/zones/{zone_id}, and ETag carries its first version.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataZone
A geographic annotation drawn on the map, such as a hazard zone, an information marker, or a custom area.
See the Zone object.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 503, 504. See Errors.
/v1/zones/{zone_id}Returns the zone, including the full geojson geometry, created_by, and the temporal validity window (start_at / end_at). This is the authoritative geometry for editing, unlike the simplified, clipped geometry served by the tile endpoint.
Path parameters
zone_idstring (uuid)
in path
Identifier of the zone the operation acts on.
Query parameters
surfacestring
in query
One of: published
Reads the published snapshot rather than the draft. published is the only accepted value: there is deliberately no draft spelling, because the param only ever narrows what the caller is served. An unrecognized value is rejected with a validation error rather than silently ignored. A read of one itinerary, or of one zone, refuses it with 403 when it is personal, owned by no organization, to the person whose it is: the published surface is what a video and an embed are made of, and a personal itinerary or zone makes neither. Every other caller reads a personal itinerary or zone as published, and since one is never published it is answered as one that does not exist.
Response 200
The zone with its geometry, level and validity window.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataZone
A geographic annotation drawn on the map, such as a hazard zone, an information marker, or a custom area.
See the Zone object.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/zones/{zone_id}Updates the zone's name, description, level and temporal validity window. Every field is optional and an omitted field keeps its current value. The area may be replaced by providing geojson, which must be a Polygon whose outline no meridian and no parallel crosses more than 512 times, every ring counted, and which is a valid polygon in degrees as sent and once projected to Web Mercator, as a map draws it: an outline too intricate, a ring that crosses itself or another ring, in either, a ring that touches itself, or a hole outside its shell is a 400 naming geojson.geometry. When omitted the existing area is carried forward, as it is. An area computed from a source held to none of these, or of more than 10,000 positions, is a 400 naming source, and nothing is written. A mode is sent with the area it describes: beside geojson any mode, beside a source only polygon, and a mode sent with neither is a 400 naming mode. Only a zone whose mode, sent or kept, is polygon takes a source: on any other mode it is a 400 naming source. is_private makes the zone private or public, independently of whether it is published. An end_at earlier than the zone's resulting start_at, whether either was sent or kept, is a 400 naming end_at. Every call writes a new revision, even one that changes nothing, so revision and updated_at move and, on a published zone, has_unpublished_changes is set: what the public surfaces serve moves only at the next postZonePublication, privacy aside, which is read from the draft and takes effect at once.
Webhook events zone.updated, recorded by the task zone.update.
Path parameters
zone_idstring (uuid)
in path
Identifier of the zone the operation acts on.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
If-Matchstring
in header
Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.
Body
The zone fields to change. Every field is optional; omitted fields are left as they are.
descriptionstring | null
in body
Free-text description of the zone, at most 100 characters as sent, stored with leading and trailing whitespace trimmed. Omit to keep the current value; null, or a value that trims to nothing, clears it.
end_atstring (date-time) | null
in body
End of the temporal validity window. Omit to keep the current value; null removes the expiration. The window a request leaves must not end before it starts: an end_at earlier than the resulting start_at, sent or kept, is a 400 naming end_at.
geojsonobject
in body
Replacement area, which replaces the stored one wholesale rather than merging into it. Optional and not nullable: omit it to keep the current area. Sent on a sourced zone, it replaces the computed area and detaches the source. Mutually exclusive with source in the same request.
is_privateboolean
in body
Whether the zone is private. A private zone is reached only with the key of the organization that owns it, so a private personal zone, owned by no organization, is reached by no key. A public zone is readable by id, read-only, by any publishable key, as last published, and it is listed only in its own organization's listings. A collection's share token reaches the zones that collection holds whatever this says. Public never grants editing, which takes a write role in the owning organization. Privacy is read from the draft, so a change takes effect at once rather than at the next publish. Omit to keep the current value.
levelstring
in body
One of: info, resolved, warning, danger
How serious the zone is, which is what a renderer picks its styling from. It carries no access meaning: a zone is visible or not by is_private and its publication, never by its level. Optional and not nullable: omit it to keep the current level.
modestring
in body
One of: polygon, circle, sensor, sector, freehand
How the area sent beside it was drawn or computed, which a client reopens the zone in. Optional and not nullable: omit it to keep the current mode. It describes an area, so it is sent with one: beside geojson any mode is taken, beside a source only polygon is, and a mode sent with neither, or another mode beside a source, is a 400 naming mode. A zone reshaped into a shape of another kind is sent the new kind's mode with its geojson.
namestring
in body
Display name of the zone, at most 30 characters as sent, and at least 2 once leading and trailing whitespace is trimmed. Optional and not nullable: omit it to keep the current name. Refused with a 409 when another zone in the organization already carries it; names are compared exactly after trimming, case included, so Alps and alps are two different names. Sending its current name again is not a conflict. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.
sourceZoneSource | null
in body
Provenance inputs for a computed zone. When provided, the zone's polygon is recomputed from these inputs and replaces the geometry, which is how a computed zone is refreshed. Only a zone whose mode, sent or kept, is polygon takes one: on any other mode it is a 400 naming source. Omit it to keep the current source; null detaches it and keeps the current area as it stands. Mutually exclusive with geojson in the same request.
start_atstring (date-time) | null
in body
Start of the temporal validity window. Omit to keep the current value; null makes the zone active immediately.
Response 200
The zone after the change, with its new revision and etag.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataZone
A geographic annotation drawn on the map, such as a hazard zone, an information marker, or a custom area.
See the Zone object.
Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 503, 504. See Errors.
/v1/zones/{zone_id}Permanently deletes the zone and removes it from every collection that held it. This action cannot be undone.
Webhook events zone.deleted, collection.zone.removed, recorded by the task zone.delete.
Path parameters
zone_idstring (uuid)
in path
Identifier of the zone the operation acts on.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
If-Matchstring
in header
Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.
Response 200
The zone is deleted and removed from every collection holding it. data is null.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.
/v1/zones/{zone_id}/publicationSets the zone's publication to its current draft: the draft's name, description, level, mode, area, validity window and source are frozen into a publication and become what the public surfaces serve. Until the first publish, the public surfaces resolve nothing for the zone: a read of it as published answers 404, and the tiles drawn from published content, Mountaya's hosted embed among them, do not draw it. After it, they serve that snapshot and are unaffected by any further draft edit until the zone is published again. The studio always reads and writes the draft, whatever is published.
Webhook events zone.published, recorded by the task zone.publish.
Path parameters
zone_idstring (uuid)
in path
Identifier of the zone the operation acts on.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
If-Matchstring
in header
Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.
Response 200
The zone as published, with status published and published_at set, and its new ETag.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataZone
A geographic annotation drawn on the map, such as a hazard zone, an information marker, or a custom area.
See the Zone object.
Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.
/v1/zones/{zone_id}/publicationTakes the zone off the public surfaces. Mountaya stops serving it from the next request: a read of it as published answers 404, the tiles drawn from published content, Mountaya's hosted embed among them, stop drawing it, and Mountaya's own caches stop serving its published tiles: they are not evicted, but nothing reaches them and they age out. An answer a shared cache between a reader and Mountaya already holds is served from there until its lifetime runs out, which taking the zone down does not shorten: at most 6 minutes for a published read of the zone (max-age=300 and stale-while-revalidate=60), and 5 for a public tile of it (max-age=300).
Webhook events zone.unpublished, recorded by the task zone.unpublish.
Path parameters
zone_idstring (uuid)
in path
Identifier of the zone the operation acts on.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
If-Matchstring
in header
Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.
Response 200
The zone unpublished, with status draft and published_at null, and its ETag. A zone that was not published is answered the same way.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataZone
A geographic annotation drawn on the map, such as a hazard zone, an information marker, or a custom area.
See the Zone object.
Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.