Reference grammar
One addressing scheme is used everywhere: in URL paths and parameters, in command payloads, and in event payloads. A value received from the map can be sent straight back to it.
| Form | Example | Names |
|---|---|---|
{building} | muntz-hall | A building |
{building}/floor/{floor} | muntz-hall/floor/2 | A floor |
{building}/{room} | muntz-hall/170 | A room |
here | here | The visitor's current position |
pin:{lat},{lng} | pin:39.1329,-84.5150 | An arbitrary coordinate |
A reference that does not resolve produces REF_NOT_FOUND rather than failing
quietly.
Why slugs and not identifiers
Buildings, floors, and rooms all have database identifiers internally. None of them appear in the protocol.
Identifiers are not stable across data updates, so a protocol that exposed them would either force integrations to depend on values nobody intends to keep, or require the kind of warning that other indoor mapping products ship alongside their event payloads. Slugs are derived from names, are meaningful to read in a URL, and are what a campus administrator can reason about.
Rooms are qualified by their building
Room slugs are unique within a building, not across a campus, so a room reference always carries its building.
The URL path is the one place this is spelled differently. In
/{campus}/{building}/{room} the building already occupies its own segment, so
the room segment is bare: /ucba/muntz-hall/170 addresses the same room as the
reference muntz-hall/170.
Event payloads report building and room as separate fields, with room
bare. Reassemble them if you intend to send the value back:
map.on("selection.changed", ({ building, room }) => {
const ref = building && room ? `${building}/${room}` : null;
});
The SDK's mount() options and React props accept either spelling and normalise
internally.
Reserved references
camera.fitTo accepts two words that are not places.
| Reference | Frames |
|---|---|
campus | Every building on the campus |
route | The route currently drawn |
Both are reserved, so a building whose slug happens to be campus or route is
shadowed by them.
Positions
here resolves to the visitor's current position, and requires that the frame
was granted geolocation access through its allow attribute. Where no position
is available the reference does not resolve.
pin:{lat},{lng} takes decimal degrees, latitude first.
Next
- Spatial routing semantics for how indoor paths relate to these references in the underlying data model.