Map views

#Map views

By the end of this guide you'll have a styled, clustered map view of a collection and a published map you can embed on any site.

#Prerequisites

• A collection with a geo field and some records — import a GeoJSON or CSV file if you're starting from scratch
• Admin access to the dashboard

#Steps

#1. Open the map view

Open your collection's record list in the dashboard. When the collection has a geo field, a view toggle appears next to the toolbar — switch from table view to map view.

The map loads the records in the current result set and reloads as you pan and zoom: viewport changes are debounced and fetched with a bounding-box filter, so only visible records are requested. Click a feature to open its popup; the popup's edit button opens the record editor.

#2. Style features

Feature styling lives in the geo field's interfaceOptions.geoDisplay. Set a base style, then add conditional rules or graduated colours driven by your data:

{
	"geoDisplay": {
		"defaultStyle": {
			"color": "#3b82f6",
			"opacity": 0.9,
			"strokeColor": "#1e40af",
			"strokeWidth": 1.5,
			"radius": 6
		},
		"rules": [
			{ "field": "status", "operator": "eq", "value": "closed", "style": { "color": "#dc2626" } }
		],
		"graduated": {
			"field": "capacity",
			"method": "step",
			"stops": [
				{ "value": 0, "color": "#dbeafe" },
				{ "value": 50, "color": "#60a5fa" },
				{ "value": 200, "color": "#1d4ed8" }
			]
		},
		"label": { "field": "name", "size": 11, "minZoom": 10 }
	}
}

Key	What it controls
defaultStyle	Base colour, opacity, stroke, and point radius for every feature
rules	Per-feature overrides matched with eq, neq, gt, lt, gte, lte, in, or between
graduated	Colour (and optionally radius) interpolated from a numeric field, linear or step
label	A text label from a field, with size, colour, minimum zoom, and halo options

#3. Configure popups

Popups are configured with interfaceOptions.popupConfig. Choose one of three modes:

Mode	Config	Behaviour
Template	"template": "{{name}} — {{status}}"	Renders the template with {{field}} placeholders
Field list	"fields": [{ "name": "capacity", "label": "Capacity", "format": "number" }]	Renders the listed fields with per-field formatting
Default	(none)	Shows a summary of the record's non-geo fields

Field formats: text, number, date, badge, link, image. You can also set maxWidth (pixels) and showEditButton.

#4. Cluster points

Point features cluster by default. Tune clustering per field under geoDisplay.clustering, or change the system-wide defaults:

Setting	Default	Description
enabled	true (system setting)	Group nearby points into clusters
radius	50	Pixel distance within which points merge into a cluster
maxZoom	14	Zoom level at which clusters break apart
colors	["#51bbd6", "#f1f075", "#f28cb1"]	Cluster colours for small, medium, and large clusters

#5. Set system-wide map defaults

Open Settings → Map to configure defaults that apply wherever no field-level override exists:

Key	Default	Description
map.basemaps	One built-in style	Available basemap styles — each has an id, name, MapLibre style URL, and attribution
map.default_basemap	First basemap	Basemap id used when a field doesn't override it
map.default_marker_color	#3b82f6	Point marker colour when no styling rules are set
map.default_marker_radius	6	Point marker radius in pixels
map.default_stroke_color	#1e40af	Line and polygon outline colour
map.default_fill_opacity	0.3	Polygon fill opacity (0–1)
map.clustering_enabled	true	Cluster points by default
map.clustering_radius	50	Cluster radius in pixels
map.clustering_max_zoom	14	Zoom level at which clusters break apart
map.cache_ttl_seconds	30	Cache lifetime for public map data queries
map.max_features_per_request	5000	Hard limit on features per geo query

When you add more than one basemap, the map view shows a style switcher so viewers can change basemaps.

#6. Publish a map

A published map is a saved, read-only map with its own URL. Open Published Maps in the dashboard and click Create Map, then pick the collection, the geo field, and a name. The map gets a URL slug and one of three access modes:

Mode	Who can view	How
public	Anyone with the link	No credentials needed
token	Anyone with the token link	The share URL carries a ?token=... parameter
password	Anyone with the password	Viewers enter the password once; access lasts 24 hours

You can also manage published maps via the API:

POST /api/v1/maps
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "name": "Campsite finder",
  "collection_name": "campsites",
  "geo_field": "location",
  "auth_mode": "public"
}

Method	Path	Description
POST	/api/v1/maps	Create a published map
GET	/api/v1/maps	List published maps
GET	/api/v1/maps/:id	Get a map's configuration
PUT	/api/v1/maps/:id	Update a map (partial)
DELETE	/api/v1/maps/:id	Delete a map
GET	/api/v1/maps/:slug/public	Get map config plus data as GeoJSON (viewer endpoint)
GET	/api/v1/maps/:slug/data	Get data only, for refreshing an open map
POST	/api/v1/maps/:slug/verify	Verify a password and start a viewer session

#7. Embed the map

Every published map has a standalone viewer at /embed/{slug} — a full-viewport map with no dashboard chrome. Copy the embed code from the Published Maps list, or write the iframe yourself:

<iframe
	src="https://your-api.example.com/embed/campsite-finder"
	width="100%"
	height="500"
	frameborder="0"
	allow="fullscreen"
></iframe>

#What you learned

• The map view is a per-collection toggle that loads records by viewport bounding box
• Feature styling, labels, popups, and clustering are configured on the geo field's interfaceOptions
• Settings → Map holds system-wide defaults for basemaps, styling, clustering, and query limits
• A published map wraps a collection and geo field in a shareable, access-controlled viewer you can embed with an iframe

#Next steps

• Spatial queries — filter map data by proximity, containment, or intersection
• Geo fields — import data in GeoJSON, CSV, KML, or GPX format