Search and directions

The read side of a map, as the public map and Waygo.js use it: search the content placed on a map, read one place, and compute routes. Every result names places by placement ID, the ID that links and Waygo.js use.

A placement is a catalog row on a particular map: the same exhibitor placed on two maps has two placement IDs. Search needs search:read; routes need routes:read. A public read-only key with those scopes is what the map itself presents.

ENDPOINTS

GET  /search/v1/:map_id/:map_view_id
GET  /search/v1/:placement_id
POST /search/v1/:map_id/placements/batch-details
POST /routes/v1/path
POST /routes/v1/path/node_to_placement
POST /routes/v1/closest

GET/search/v1/:map_id/:map_view_id

Search a map

Full-text search over everything placed on the map: names, catalog titles and every column. Results are ranked by relevance. The map_view_id is the map's default view (the load endpoint returns it).

Parameters

Name
q
Type
string
Description
The query. Required.
Name
floor
Type
integer
Description
Only places on this level.
Name
skip / limit
Type
integer
Description
Paging; limit up to 100, default 20.
Name
sort
Type
string[]
Description
Override the relevance order by a field (floor, -floor).

Each hit

Name
placement_id
Type
string
Description
The place.
Name
floor
Type
integer
Description
Its level.
Name
location
Type
GeoJSON Point
Description
Where its label sits, in the drawing's coordinates.
Name
contextual_location
Type
string
Description
Where it is, in words: “201, Expo Hall, Acme Expo 2027”.
Name
catalog
Type
object
Description
The catalog's title, columns and special keys.
Name
content
Type
object
Description
{ content_id, data }: the row.

GET /search/v1/:map_id/:map_view_id

API KEY SCOPE

search:read

curl "https://api.waygomaps.com/search/v1/acme-expo-2027/k3Qm7vX2S8aB1nR9tLpYwA?q=acme&limit=5" \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

Response

[
  {
    "placement_id": "d7e1f77ece5f493093ccd1d09e009f5c",
    "floor": 0,
    "location": { "type": "Point", "coordinates": [33.0, 2.0] },
    "contextual_location": "201, Expo Hall, Acme Expo 2027",
    "catalog": { "catalog_id": "exhibitors", "title": "Exhibitors", "data_schema": { "…": "…" }, "content_title_key": "Company" },
    "content": { "content_id": "…", "data": { "Company": "Acme Robotics", "Booth": "201" } }
  }
]

GET/search/v1/:placement_id

Place details

One place with its catalog, its row, its parent (the booth a sub-item sits in) and its children (items placed on it).

GET /search/v1/:placement_id

API KEY SCOPE

search:read

curl https://api.waygomaps.com/search/v1/d7e1f77ece5f493093ccd1d09e009f5c \
  -H "Waygo-API-Key: $WAYGO_API_KEY"

Response

{
  "placement_id": "d7e1f77e…",
  "floor": 0,
  "location": { "type": "Point", "coordinates": [33.0, 2.0] },
  "contextual_location": "201, Expo Hall, Acme Expo 2027",
  "catalog": { "catalog_id": "exhibitors", "title": "Exhibitors", "…": "…" },
  "content": { "content_id": "…", "data": { "Company": "Acme Robotics", "Booth": "201" } },
  "parent": null,
  "children": {}
}

POST/search/v1/:map_id/placements/batch-details

Resolve many placements

Up to 200 placement IDs at once. found holds the places that exist on the map in request order; missing lists IDs that no longer exist (a deleted row), which is safe to act on.

POST /search/v1/:map_id/placements/batch-details

API KEY SCOPE

search:read

curl -X POST https://api.waygomaps.com/search/v1/acme-expo-2027/placements/batch-details \
  -H "Waygo-API-Key: $WAYGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "placement_ids": ["d7e1f77ece5f493093ccd1d09e009f5c", "0000deleted"] }'

Response

{ "map_id": "acme-expo-2027", "found": [ { "placement_id": "d7e1f77e…", "…": "…" } ], "missing": ["0000deleted"] }

POST/routes/v1/path

Directions between two places

The walking route between two placements, as legs per level with steps.

Body

Name
map_id
Type
string
Description
The map.
Name
start_placement_id
Type
string
Description
Where the route starts.
Name
end_placement_id
Type
string
Description
The destination.

To start at a walking-path node instead (what a kiosk does), POST /routes/v1/path/node_to_placement with start_node_id in place of start_placement_id; a kiosk's node comes from its resolve.

POST /routes/v1/path

API KEY SCOPE

routes:read

curl -X POST https://api.waygomaps.com/routes/v1/path \
  -H "Waygo-API-Key: $WAYGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "map_id": "acme-expo-2027", "start_placement_id": "8b54fe81…", "end_placement_id": "d7e1f77e…" }'

Response

{
  "unit": "Meters",
  "legs": [
    {
      "floor": 0,
      "indicator": "1",
      "steps": [
        { "instruction": "depart", "text": "Depart Registration and continue straight", "path": [[-34.0, 2.0], [-20.0, 2.0]], "distance": 14.0 },
        { "instruction": "arrive", "text": "Arrive at Acme Robotics on the right", "path": [[-20.0, 2.0], [33.0, 2.0]], "distance": 53.0 }
      ]
    }
  ]
}

POST/routes/v1/closest

Nearest walking path

The walking-path node nearest a point on a level, and how far it is. What the kiosk builder shows while a marker is dragged.

Body

Name
map_id
Type
string
Description
The map.
Name
floor_num
Type
integer
Description
The level.
Name
lnglat
Type
[lng, lat]
Description
The point. Or coordinate: [x, y] in the drawing's coordinates; send exactly one.

Answers 409 level_without_walking_paths when the level has none.

POST /routes/v1/closest

API KEY SCOPE

routes:read

curl -X POST https://api.waygomaps.com/routes/v1/closest \
  -H "Waygo-API-Key: $WAYGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "map_id": "acme-expo-2027", "floor_num": 0, "lnglat": [-122.41941, 37.77493] }'

Response

{ "node_id": "n0-6", "map_source_floor": 0, "position_x": 36.0, "position_y": 2.0, "distance": 2.83, "unit": "Meters", "lnglat": [-122.41943, 37.77492], "…": "…" }