Maps

A map is one venue map with a public address (https://maps.waygomaps.com/{map_id}). Your Waygo team creates it; this API reads it, changes its settings, publishes it and takes it live, exactly as the dashboard's map page does.

Every endpoint here is scoped to your account (or a sub-account through the Waygo-Account header) and needs maps:read or maps:write. Whether a call is allowed also depends on the map's state: the overview's capabilities object tells you before you try.

ENDPOINTS

GET  /maps/v1
GET  /maps/v1/:map_id
GET  /maps/v1/:map_id/overview
GET  /maps/v1/:map_id/usage
GET  /maps/v1/:map_id/publish-status
PUT  /maps/v1/:map_id/configuration
POST /maps/v1/:map_id/publish
POST /maps/v1/:map_id/live
POST /maps/v1/:map_id/offline
POST /maps/v1/:map_id/preview-link
POST /maps/v1/:map_id/floor-plans
GET  /maps/v1/:map_id/floor-plans
GET  /map-views/v1/:map_id/load   (public)

The map object

Properties

Name
map_id
Type
string
Description
The map's ID and the last part of its public address. Set at creation; never changes.
Name
account_id
Type
string
Description
The account the map belongs to.
Name
name
Type
string
Description
The map's name, shown in the search bar and the browser tab.
Name
unit_type
Type
'Meters' | 'Feet'
Description
The unit directions are given in.
Name
status
Type
'draft' | 'live' | 'offline'
Description
Whether the map is public. See Publishing and going live.
Name
status_reason
Type
string | null
Description
Who moved it last: customer, staff, license_expired.
Name
status_changed_at
Type
timestamp | null
Description
When the status last changed.
Name
first_published_at
Type
timestamp | null
Description
When Waygo first published the base map.
Name
license
Type
object | null
Description
{ starts_at, ends_at, note }: the map's license period, set by Waygo.
Name
floor_labels
Type
array
Description
Your per-level overrides of the level names: one { name, indicator } or null per level, by index.
Name
map_source_id
Type
string
Description
The floors the map is built on. Two maps can share floors.
Name
default_map_view_id
Type
string
Description
The map's default view: the view ID that appears in links.
Name
publish_limits
Type
object | null
Description
A per-map publish allowance set by Waygo, when one differs from the account's.
Name
created_at / updated_at
Type
timestamp
Description
Timestamps.

The map object

{
  "map_id": "acme-expo-2027",
  "account_id": "dash-dev-acct",
  "name": "Acme Expo 2027",
  "unit_type": "Meters",
  "status": "live",
  "status_reason": "customer",
  "status_changed_at": "2026-08-09T14:02:11",
  "first_published_at": "2026-08-08T23:44:00",
  "license": { "starts_at": "2026-08-04T00:00:00", "ends_at": "2027-08-04T00:00:00", "note": null },
  "floor_labels": [null, { "name": "Mezzanine", "indicator": "M" }],
  "map_source_id": "dash-dev-src",
  "default_map_view_id": "k3Qm7vX2S8aB1nR9tLpYwA",
  "publish_limits": null,
  "created_at": "2026-07-01T09:00:00",
  "updated_at": "2026-09-18T19:44:21"
}

GET/maps/v1

List maps

Every map of the account, newest first, with the facts the dashboard's Maps list shows on top of the map object.

Optional parameters

Name
skip
Type
integer
Description
Number of maps to skip. Default 0.
Name
limit
Type
integer
Description
Maps per page. Default 20.

Extra fields per map

Name
public_url
Type
string
Description
The map's public link.
Name
license_ends_at
Type
timestamp | null
Description
When the license ends.
Name
level_count
Type
integer
Description
Number of levels.
Name
placed_count
Type
integer
Description
Content rows placed on the map.
Name
floor_plans_awaiting_build
Type
integer
Description
Uploaded floor plans Waygo has not built yet.

GET /maps/v1

API KEY SCOPE

maps:read

curl "https://api.waygomaps.com/maps/v1?limit=20" \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

Response

{
  "maps": [
    {
      "map_id": "acme-expo-2027",
      "name": "Acme Expo 2027",
      "status": "live",
      "public_url": "https://maps.waygomaps.com/acme-expo-2027",
      "license_ends_at": "2027-08-04T00:00:00",
      "level_count": 2,
      "placed_count": 301,
      "floor_plans_awaiting_build": 0
      // …the map object's other fields
    }
  ],
  "total": 4,
  "skip": 0,
  "limit": 20
}

GET/maps/v1/:map_id

Retrieve a map

The map object alone. For everything the map page shows, use the overview.

GET /maps/v1/:map_id

API KEY SCOPE

maps:read

curl https://api.waygomaps.com/maps/v1/acme-expo-2027 \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

GET/maps/v1/:map_id/overview

The map overview

Everything the dashboard's map page renders, in one read: the map, its floors and floor plans, presentation, publishing state, content counts, the draft checklist, links, and what the caller may do.

Response fields

Name
map
Type
object
Description
The map object.
Name
public_url
Type
string
Description
The public link.
Name
license
Type
object
Description
{ active, expired, ending_soon, days_remaining, starts_at, ends_at }.
Name
floors
Type
object
Description
map_source_id, name, level_count, shared_with (other maps on the same floors), levels[] (each with index, indicator, name, default_indicator, default_name, overridden), base_map (its publish state), paths_version.
Name
floor_plans
Type
array
Description
The map's floor plans (see Floor plans).
Name
floor_plans_awaiting_build
Type
integer
Description
Uploaded plans Waygo has not built yet.
Name
presentation
Type
object
Description
{ map_view_id, style_set, default_floor, suggested_search_terms }.
Name
publishing
Type
object
Description
The same shape as the publish status below.
Name
recent_publishes
Type
array
Description
Recent publish runs.
Name
content
Type
array
Description
Per catalog: { catalog_id, title, total_rows, placed_rows, last_change_at }.
Name
checklist
Type
object
Description
The draft checklist: { map_created, floor_plans: { uploaded, building, failed, ready, total_levels }, built, can_go_live }.
Name
links
Type
object
Description
{ kiosk_count, reservation_feature_enabled, embed_url, embed_snippet }.
Name
usage_window_days
Type
integer
Description
The usage window (7).
Name
capabilities
Type
object
Description
Per action, { allowed, reason }. Actions include edit_general, edit_floor_labels, edit_presentation, upload_floor_plan, delete_uploaded_floor_plan, publish_content_labels, go_live, take_offline, preview, manage_links. reason explains a refusal: license_inactive, map_not_ready, publish_allowance_exceeded, publish_in_progress, already_live, already_offline, nothing_to_preview, staff_only, missing_scope.

GET /maps/v1/:map_id/overview

API KEY SCOPE

maps:read

curl https://api.waygomaps.com/maps/v1/acme-expo-2027/overview \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

Response (abridged)

{
  "map": { "map_id": "acme-expo-2027", "status": "live", "…": "…" },
  "public_url": "https://maps.waygomaps.com/acme-expo-2027",
  "license": { "active": true, "expired": false, "ending_soon": false, "days_remaining": 320 },
  "floors": {
    "level_count": 2,
    "levels": [
      { "index": 0, "indicator": "1", "name": "Expo Hall", "overridden": false },
      { "index": 1, "indicator": "M", "name": "Mezzanine", "default_name": "Level 2", "overridden": true }
    ],
    "paths_version": 3
  },
  "presentation": { "default_floor": 0, "suggested_search_terms": ["Registration", "Coffee"] },
  "content": [
    { "catalog_id": "exhibitors", "title": "Exhibitors", "total_rows": 301, "placed_rows": 298 }
  ],
  "links": {
    "kiosk_count": 2,
    "embed_url": "https://maps.waygomaps.com/acme-expo-2027?embed=1",
    "embed_snippet": "<iframe src=\"…\" …></iframe>"
  },
  "capabilities": {
    "publish_content_labels": { "allowed": true, "reason": null },
    "go_live": { "allowed": false, "reason": "already_live" },
    "manage_links": { "allowed": true, "reason": null }
  }
}

GET/maps/v1/:map_id/usage

Usage

What the dashboard's Usage section shows: loads, searches, directions and place views over the window, with the previous window for comparison.

Optional parameters

Name
days
Type
integer
Description
The window in days. Default 7.

GET /maps/v1/:map_id/usage

API KEY SCOPE

maps:read

curl "https://api.waygomaps.com/maps/v1/acme-expo-2027/usage?days=7" \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

Response

{
  "map_id": "acme-expo-2027",
  "days": 7,
  "from": "2026-09-11T00:00:00",
  "to": "2026-09-18T00:00:00",
  "loads_per_day": [{ "date": "2026-09-12", "count": 61 }, { "date": "2026-09-13", "count": 74 }],
  "totals": { "loads": 492, "searches": 27, "routes": 42, "place_views": 63 },
  "kiosk_route_share": { "kiosk": 21, "other": 21 },
  "top_searches": [{ "term": "registration", "count": 7 }, { "term": "coffee", "count": 7 }],
  "prior": { "loads": 302, "searches": 28, "routes": 30, "place_views": 28 }
}

GET/maps/v1/:map_id/publish-status

Publish status

The state of the two layers, the running publish if any, the allowance and recent runs. Poll it every few seconds while active_run is set. See Publishing and going live for what the layers mean.

Response fields

Name
status / status_reason
Type
string
Description
The map's status.
Name
license
Type
object
Description
The license summary.
Name
active_run
Type
object | null
Description
The publish run in flight.
Name
layers.content_labels
Type
object
Description
last_published_at, publish_status, pending_changes, stale, auto_publish { enabled, threshold, cooldown_seconds, forecast } where forecast is not_due, due, cooling_down, manual_first or disabled.
Name
layers.base_map
Type
object
Description
last_published_at, publish_status, stale, last_error.
Name
readiness
Type
object
Description
{ ready, blockers[], warnings[] } for going live.
Name
allowance
Type
object
Description
{ used_today, per_day, min_interval_seconds, next_available_at, scope, exempt }.
Name
recent_runs
Type
array
Description
Publish runs, newest first.

GET /maps/v1/:map_id/publish-status

API KEY SCOPE

maps:read

curl https://api.waygomaps.com/maps/v1/acme-expo-2027/publish-status \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

Response (abridged)

{
  "status": "live",
  "active_run": null,
  "layers": {
    "content_labels": {
      "last_published_at": "2026-09-17T22:49:00",
      "publish_status": "published",
      "pending_changes": 18,
      "stale": true,
      "auto_publish": { "enabled": true, "threshold": 500, "cooldown_seconds": 600, "forecast": "not_due" }
    },
    "base_map": { "last_published_at": "2026-08-08T23:44:00", "publish_status": "published", "stale": false }
  },
  "readiness": { "ready": true, "blockers": [], "warnings": [] },
  "allowance": { "used_today": 0, "per_day": 12, "min_interval_seconds": 600, "next_available_at": null, "scope": "account", "exempt": false },
  "recent_runs": [
    { "run_id": "…", "targets": ["content_labels"], "requested_role": "customer", "trigger": "manual", "status": "succeeded", "started_at": "2026-09-17T22:49:00", "finished_at": "2026-09-17T22:51:30", "counted_against_allowance": true }
  ]
}

PUT/maps/v1/:map_id/configuration

Update settings

What the dashboard's Map settings panel saves. Send only the sections you change; each section is authorised on its own, and a section you may not edit answers 403 section_not_editable (nothing is silently dropped).

Sections

Name
general
Type
object
Description
{ name?, unit_type? }.
Name
floor_labels
Type
array
Description
One entry per level by index: { name?, indicator? } to override, null to use Waygo's default. The indicator is 1 to 3 characters.
Name
presentation
Type
object
Description
{ default_floor?, suggested_search_terms? }: the level the map opens on and the chips under the search bar.

The floor structure, anchor point, shared floors, map style, license and allowances are set by Waygo; sending those sections answers 403.

Answers the updated overview.

PUT /maps/v1/:map_id/configuration

API KEY SCOPE

maps:write

curl -X PUT https://api.waygomaps.com/maps/v1/acme-expo-2027/configuration \
  -H "Waygo-API-Key: $WAYGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "general": { "name": "Acme Expo 2027" },
    "floor_labels": [null, { "name": "Mezzanine", "indicator": "M" }],
    "presentation": { "default_floor": 0, "suggested_search_terms": ["Registration", "Coffee", "Restrooms"] }
  }'

Refused section

{ "error": "section_not_editable", "section": "anchor", "reason": "staff_only" }

POST/maps/v1/:map_id/publish

Publish

Bake the map's content labels. Content changes are already live; publishing makes them permanent and fast to load, and the map republishes itself after 500 changes, so call this only when you want it now. Runs as a job: the response is the run; follow it through the publish status.

Body

Name
targets
Type
array
Description
["content_labels"]. (The base map is published by Waygo.)

Errors

Name
409 publish_in_progress
Description
A run is already in flight.
Name
409 license_inactive
Description
The map's license has ended.
Name
429 publish_allowance_exceeded
Description
Today's allowance is spent or the interval has not passed; next_available_at and a Retry-After header say when.

POST /maps/v1/:map_id/publish

API KEY SCOPE

maps:write

curl -X POST https://api.waygomaps.com/maps/v1/acme-expo-2027/publish \
  -H "Waygo-API-Key: $WAYGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targets": ["content_labels"] }'

Response (202)

{
  "run_id": "7f3c…",
  "map_id": "acme-expo-2027",
  "targets": ["content_labels"],
  "requested_role": "customer",
  "trigger": "manual",
  "status": "running",
  "target_states": { "content_labels": { "status": "queued" } },
  "counted_against_allowance": true,
  "started_at": "2026-09-18T19:44:21",
  "finished_at": null
}

429

{ "error": "publish_allowance_exceeded", "reason": "daily_limit_reached", "used_today": 12, "per_day": 12, "next_available_at": "2026-09-19T00:00:00" }

POST/maps/v1/:map_id/live

Go live

Make the map public. Refused with 409 map_not_ready and a blockers list while Waygo is still building it, and with 409 license_inactive after the license ends. The first time a map goes live, Waygo bakes its content labels automatically (a system run that does not count against the allowance). Answers the updated overview.

POST /maps/v1/:map_id/live

API KEY SCOPE

maps:write

curl -X POST https://api.waygomaps.com/maps/v1/acme-expo-2027/live \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

409

{ "error": "map_not_ready", "blockers": ["base_map_not_published"] }

POST/maps/v1/:map_id/offline

Take offline

Stop serving the map. Every link and kiosk shows “This map is not available right now” until it goes live again; nothing is deleted. Answers the updated overview.

POST /maps/v1/:map_id/offline

API KEY SCOPE

maps:write

curl -X POST https://api.waygomaps.com/maps/v1/acme-expo-2027/offline \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

POST/maps/v1/:map_id/preview-link

Preview link

A signed link that opens a draft or offline map for 24 hours. Refused with 409 map_not_ready on a draft whose base map Waygo has not published yet (there is nothing to show). The token is what Waygo.js takes as its preview option.

POST /maps/v1/:map_id/preview-link

API KEY SCOPE

maps:read

curl -X POST https://api.waygomaps.com/maps/v1/acme-winter-market-2025/preview-link \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

Response

{
  "token": "bWFwX3ByZXZpZXd8YWNtZQ.c2ln",
  "url": "https://maps.waygomaps.com/acme-winter-market-2025?preview=bWFwX3ByZXZpZXd8YWNtZQ.c2ln",
  "expires_at": "2026-09-19T19:44:21"
}

Floor plans

POST /maps/v1/:map_id/floor-plans uploads drawings for the map and GET /maps/v1/:map_id/floor-plans lists them. Both are documented under Floor plans.

GET/map-views/v1/:map_id/load

Load a map (public)

What the public map and Waygo.js call to open a map. No authentication; a draft, offline or expired map answers 404 map_not_available unless a valid preview token is given.

Optional parameters

Name
map_view_id
Type
string
Description
A specific view; defaults to the map's default view.
Name
preview
Type
string
Description
A preview token.

GET /map-views/v1/:map_id/load

PUBLIC

no key

curl https://api.waygomaps.com/map-views/v1/acme-expo-2027/load

Response

{
  "account_id": "dash-dev-acct",
  "map_id": "acme-expo-2027",
  "map_view_id": "k3Qm7vX2S8aB1nR9tLpYwA",
  "map_name": "Acme Expo 2027",
  "map_view_name": "Acme Expo 2027 — Main",
  "status": "live",
  "preview": false,
  "floors": [{ "name": "Expo Hall", "indicator": "1" }, { "name": "Mezzanine", "indicator": "M" }],
  "default_floor": 0,
  "suggested_search_terms": ["Registration", "Coffee"],
  "reference_coordinate": [-122.41941, 37.77493],
  "coordinate_scaling_multiplier": 30.0,
  "style_id": "cmsn…"
}