Map Client Guide

Build an interactive map interface that shows resource locations, floor plans, availability, and booking previews on a geographic or building map.

Concepts

Resource Locations

The core booking resources data layer used for:

Creating map markers
Displaying the resource booking card
Determining availability status

Fetch resource coordinates along with optional availability and viewport filters.

Resource Map Previews

Lightweight metadata for each building map, used for:

Resource map dropdown
Determining initial map position
Identifying maps within the current viewport
Referencing the GeoJSON URL for rendering

Resource Maps

Full GeoJSON + layer data for a single building floor plan. Only fetched when a map enters the viewport.

Booking Previews

Partially anonymized booking data used to:

Display user avatars on the map
Highlight resources booked by the current user

Viewport Filtering

A map-move event (throttled to 200ms) triggers viewport checks. Resource maps within the viewport are mounted; those outside are unmounted.

Marker Types

Type	Description
Cluster	Groups nearby resources at low zoom levels
Resource (on map)	Resources assigned to a floor plan (visible up to zoom 15)
Resource (standalone)	Resources without a floor plan (visible at all zoom levels)

Initialization Flow

Fetch initial data

Fetch Resource Locations (without child resources), Resource Map Previews, and the initial bounding box for the active filters — location, availability, category, and context (community / organization / customer account). Do not apply viewport filtering at this stage.

Determine initial map position

Condition	Action
Single resource, no map previews	Center on resource coordinates at zoom 18
Single resource map preview	Fit to map preview bounding box; apply pitch/rotation
Multiple resource map previews	Fit to initial BBox from the query response

Display the Resource Map Dropdown

with all available floor plans.

Initialize the map

with the position from step 2.

On map load:

Play the starting animation
Mount markers (see Mounting Markers)
Mount resource maps (see Resource Map Management) within the initial viewport
Apply any pre-selected resource features
Register all relevant events

Interaction Flow

Zoom Level	Behavior
< 15	Only markers and clusters visible; no floor plans
≥ 15	Floor plans + standalone markers visible; enable Viewport Filtering
≥ 20	Booking previews visible

Availability Filter Update Flow

On filter change:

Fetch resource locations with map previews
Update active markers

If mounted resource maps are included in the new previews:

Fetch availability data
Update resource feature states (section below)

Else:

Remove active resource maps
Re-run initialization flow from step 2

Mounting Markers

1. Add GeoJSON source:

map.addSource(MarkerSourceId, {
  type: 'geojson',
  data: { type: 'FeatureCollection', features: [] },
  cluster: true,
  clusterMaxZoom: 15,
  clusterRadius: 50,
  promoteId: 'id',
})

2. Add layers:

Circle layer — clustered marker circles (maxzoom: 15)
Symbol layer — cluster count labels (maxzoom: 15)
Circle layer — markers for resources on a floor plan (maxzoom: 15)
Circle layer — standalone markers (all zoom levels)

3. Register events:

Hover events for all marker layers
Cluster click → decluster
Standalone marker click → zoom to level 21 → show resource popup
Floor-plan marker click → zoom to level 15.5

Viewport Filtering

Triggered by the map move event, throttled to 200ms. Store resource map previews in an R-Tree indexed by bounding box for fast spatial lookups. Update the R-Tree whenever resource map preview data changes. Flow:

Get viewport bounds
Get viewport center
Search R-Tree for overlapping maps
Mount maps newly within the viewport
Unmount maps that left the viewport
Sort overlapping maps by distance to viewport center
Activate the layer control for the closest (focused) map

Resource Map Management

Mounting

Add GeoJSON source (requires: GeoJSON data URL from map preview, resource map ID):

map.addSource(resourceMapId, {
  type: 'geojson',
  data: URL,
  promoteId: 'id',
})

Add style layers (minzoom: 15)
Register events:
- Hover events (mouseenter, mouseleave, mousemove) for live resource features
- Click event → show resource popup
Add Booking Preview data (see below)
Fetch availability for all active resource features
Update feature states using map.setFeatureState():

Availability	Background Color
Unavailable	Grey
Available	Green
Unknown	Blue (selectable highlight)

Unmounting

Remove Booking Preview data
Deregister events (map.off())
Remove layers (map.removeLayer())
Remove GeoJSON source (map.removeSource())

Updating Data

Get the layer data source
Get the data source (map.getSource())
Update with source.setData(newData)

Shared maps (managed organizations)

A managing organization can publish a floor plan to every organization it manages. Sharing is stored on the map resource, not as a separate share object.

PATCH /api/v1/resource-maps/{map_uuid}?o={master_org_id}

{
  "data": {
    "type": "resource-maps",
    "id": "{map_uuid}",
    "attributes": {
      "settings": {
        "sharedWithManagedOrganizations": true
      }
    }
  }
}

Set sharedWithManagedOrganizations to false to stop sharing. Linked managed organizations are detached, and the map disappears from their GET /api/v1/resource-maps index.

Who can see and edit a shared map

Actor	Index / read	Update map (name, geometry, settings)	Assign own resources on the map
Owning (managing) organization	Yes	Yes	Yes
Managed organization	Yes, automatically when the flag is `true`	No (`403`)	Yes, own resources only
Unrelated organization	No	No	No

On the owner read, JSON:API meta.shared_organization_ids lists managed organization IDs that currently have resources assigned on the map. Managed organizations do not receive that meta.

GET /api/v1/resource-maps?o={org_id}&filter[shared_with_managed_organizations]=true

This filters the owner’s maps by the setting. It is not a way for a managed organization to opt in: shared maps already appear in that organization’s index.

Booking Previews on Maps

Fetch booking previews for the resources within a mounted floor plan and overlay avatar markers on the corresponding resource features. Use map.setFeatureState() to attach preview data to individual GeoJSON features for rendering. Refresh booking previews whenever a booking WebSocket event is received on the resources.{resourceId} channel.

API Endpoints Used

Endpoint	Purpose
`GET /api/v1/resources` with `filter[location]`	Resource locations
`GET /api/v1/resource-map-previews`	Map preview metadata
`GET /api/v1/resource-maps`	Map index, including maps shared by a managing organization
`GET /api/v1/resource-maps/{id}`	Full GeoJSON for a floor plan
`PATCH /api/v1/resource-maps/{id}`	Update map attributes, including `settings.sharedWithManagedOrganizations`
`GET /api/v1/booking-previews`	Booking avatar data
`GET /api/v1/availability`	Resource availability status

Guides

Customer API

Admin API

Data models

Customer internal API

Admin internal API

Identity API

Additional internal API

Map Client Guide

Concepts

Resource Locations

Resource Map Previews

Resource Maps

Booking Previews

Viewport Filtering

Marker Types

Initialization Flow

Interaction Flow

Availability Filter Update Flow

Mounting Markers

Viewport Filtering

Resource Map Management

Mounting

Unmounting

Updating Data

Shared maps (managed organizations)

Who can see and edit a shared map

Booking Previews on Maps

API Endpoints Used

​Concepts

​Resource Locations

​Resource Map Previews

​Resource Maps

​Booking Previews

​Viewport Filtering

​Marker Types

​Initialization Flow

​Interaction Flow

​Availability Filter Update Flow

​Mounting Markers

​Viewport Filtering

​Resource Map Management

​Mounting

​Unmounting

​Updating Data

​Shared maps (managed organizations)

​Enable or disable sharing

​Who can see and edit a shared map

​Filter maps by the sharing flag

​Booking Previews on Maps

​API Endpoints Used

Concepts

Resource Locations

Resource Map Previews

Resource Maps

Booking Previews

Viewport Filtering

Marker Types

Initialization Flow

Interaction Flow

Availability Filter Update Flow

Mounting Markers

Viewport Filtering

Resource Map Management

Mounting

Unmounting

Updating Data

Shared maps (managed organizations)

Enable or disable sharing

Who can see and edit a shared map

Filter maps by the sharing flag

Booking Previews on Maps

API Endpoints Used