Map-Grid URL Parameters

Complete reference for all URL parameters supported by the map-grid embed page.

Table of Contents

• Required Parameters
• Content & Data
• Map Viewport
• Map Display
• 3D & Effects (styleConfig)
• Markers
• Location Dots
• Clustering
• Grouping (Co-located Markers)
• Boundary
• Filters
• Grid/List View
• Card Display
• Theme
• Advanced
• Not URL-Controllable

---

Required Parameters

Parameter	Type	Default	Description
slug / boundary	string	-	Location slug for fetching boundary and data (e.g., "austin", "dc", "westwood")
list	string	-	Alternative to slug. List slug that provides configuration from the Lists API

Note: Either slug (or boundary) or list should be provided:

• slug: Fetches boundary and places within that geographic area
• list: Fetches list configuration which may include an organization (boundary), search filters, and theme settings

When using list:

• If the list has an organization, its slug is used as the boundary
• If the list has no organization, places are fetched globally using the list's filters and the map centers on markers
• URL parameters override list configuration (e.g., ?list=foo&editorialCategory=bar uses bar instead of list's default)

---

Content & Data

Parameter	Type	Default	Description
type	string	"places"	Content type: "places" or "events"
vibes	string	-	Comma-separated list of vibes to filter by (e.g., "chill,artsy")
categories	string	-	Comma-separated list of categories to filter by
tags	string	-	Comma-separated list of tags to filter by
editorial_categories	string	-	Comma-separated list of editorial categories (aliases: editorial_category, editorialCategory)
strictFilter	boolean	false	When true, applies strict taxonomy filtering (AND logic)
dist / radius	number	-	Radius in meters for proximity search
hideNoImageItems	boolean	-	Hide items that don't have images
ordering / sort	string	"-score_combined"	Sort order for results (see below)

Sort Order (ordering / sort)

Controls how places are sorted in the grid/list.

Value	Description
name	Alphabetical by place name (A-Z)
-score_combined	Default. By relevance/popularity score (highest first)
-vibe_count	By number of vibes (most vibes first)

---

Map Viewport

Parameter	Type	Default	Description
latitude / lat	number	From boundary	Initial map center latitude
longitude / lng	number	From boundary	Initial map center longitude
zoom	number	From boundary	Initial zoom level (0-22)
bearing	number	0	Map rotation in degrees (0-360)
pitch	number	0	Map tilt in degrees (0-85)
zoomMode	string	"fit-boundary"	Initial zoom behavior: "fit-boundary" (fit to boundary polygon), "fit-markers" (fit to all markers), or "custom" (use explicit lat/lng/zoom)
refitMarkersOnFilterChange	boolean	true	When true and zoomMode="fit-markers", re-zoom to fit markers whenever filters change

Zoom Mode Details

The zoomMode parameter controls how the map determines its initial viewport:

Value	Behavior
fit-boundary	Default. Fits the map to the boundary polygon returned by the API
fit-markers	Calculates bounds from all marker coordinates and fits the map to show all markers with padding
custom	Uses explicit latitude, longitude, and zoom parameters; ignores boundary/marker bounds

Example - Fit to markers with auto-refit:

/embed/map-grid?slug=austin&zoomMode=fit-markers&refitMarkersOnFilterChange=true

---

Map Display

Parameter	Type	Default	Description
mapStyle	string	Vibemap default	Mapbox style URL (e.g., "mapbox://styles/mapbox/streets-v12")
mapHeight	number/string	"100%"	Map container height (px or CSS value)
showBoundary	boolean	true	Show boundary polygon on map
showMarkers	boolean	true	Show place/event markers
showMarkersOutOfBoundary	boolean	Auto	Show markers outside boundary (auto-enabled with radius/strictFilter)
showMapCards	boolean	true	Show info cards when clicking markers
showHeat	boolean	true	Show heatmap layer
map3d	boolean	false	Legacy 3D mode (use terrain3d instead)

---

3D & Effects (styleConfig)

These parameters control Mapbox GL terrain, weather effects, and layer visibility.

Terrain

Parameter	Type	Default	Description
terrain3d	boolean	false	Enable 3D terrain elevation
terrainExaggeration	number	1.0	Terrain height multiplier (0.1-3.0)
buildings3d	boolean	false	Enable 3D building extrusions
hillshade	boolean	false	Enable hillshade relief shading

Weather Effects

Parameter	Type	Default	Description
fog	boolean	false	Enable atmospheric fog effect
fogDistance	number	10	Fog visibility distance (1-20 km)
snow	number/boolean	false	Snow effect intensity (0-1, or true for 0.5)
rain	number/boolean	false	Rain effect intensity (0-1, or true for 0.5)

Layer Visibility

Parameter	Type	Default	Description
hideLayers	string	-	Comma-separated layer IDs to hide (e.g., "poi-label,road-label")
showLayers	string	-	Comma-separated layer IDs to show (overrides theme defaults)

Common Layer IDs: poi-label, road-label, transit-label, water-label, place-label, building, road, landuse

---

Markers

Parameter	Type	Default	Description
markerStyle	string	"mixed"	Marker display style: "mixed", "icons", "images", "only_featured"
markerLabels	string	"hide"	Label display: "hide", "featured", "all"
maxImageMarkers	number	Theme default	Max number of image markers to show
maxIconMarkers	number	Theme default	Max number of icon markers to show

---

Location Dots

Shows small dots at every GeoJSON location regardless of clustering, marker limits, or other display restrictions. Useful for showing the full extent of data when markers are limited.

Parameter	Type	Default	Description
showDots	boolean	false	Enable dots at all GeoJSON locations
dotsColor	string	Theme accent	Dot fill color (hex, e.g., "9B59B6" or "#9B59B6")
dotsRadius	number	4	Dot radius in pixels
dotsOpacity	number	1	Dot opacity (0-1)
dotsStrokeColor	string	-	Optional stroke/outline color for dots
dotsStrokeWidth	number	0	Stroke width in pixels (only applies if color is set)

Example - Show Dots with Custom Styling

/embed/map-grid?slug=austin&showDots=true&dotsColor=4a90e2&dotsRadius=3&dotsOpacity=0.5

---

Clustering

Parameter	Type	Default	Description
shouldCluster	boolean	false	Enable marker clustering
clusterRadius	number	Theme default	Pixel radius for clustering (typically 35-80)
clusterMaxZoom	number	Theme default	Max zoom level for clustering (integer, typically 14-18)

---

Grouping (Co-located Markers)

Groups markers that are at the same location (e.g., multiple events at the same venue). When clicked, groups expand to show individual items using either "spider" mode (circular spread) or "list" mode (scrollable popup).

Parameter	Type	Default	Description
enableGrouping	boolean	true	Enable grouping of co-located markers
groupingTolerance	number	3	Distance in meters within which items are considered co-located
spiderModeMaxItems	number	8	Max items for "spider" expansion (circular spread); larger groups show a scrollable list instead

How Grouping Works

1. Detection: Items within groupingTolerance meters of each other are grouped together
2. Display: Groups show a purple marker with a count badge indicating the number of items
3. Expansion modes:
   • Spider mode (≤ spiderModeMaxItems): Items spread out in a circle around the centroid with connecting lines
   • List mode (> spiderModeMaxItems): A scrollable popup appears with all items listed
4. Collapse: Click the X button at the centroid (spider mode) or close the popup (list mode)

Grouping vs Clustering

Feature	Grouping	Clustering
Purpose	Items at the same address/venue	Visual decluttering of nearby markers
Tolerance	~3 meters (same building)	35-80 pixels (screen distance)
Expansion	Spider web or scrollable list	Zoom to cluster bounds
Color	Purple	Teal (places) or Red (events)
When	Always (co-located items exist)	When zoomed out

Both features can be enabled simultaneously - clustering happens at zoom-out levels, grouping handles co-located items at any zoom level.

---

Boundary

Display

Parameter	Type	Default	Description
boundaryFilter	string	-	Filter to specific polygon by name (for MultiPolygon boundaries)
showBoundarySelectorList	boolean	true	Show boundary selector dropdown for MultiPolygon boundaries
boundarySelectorLabel	string	"Boundaries"	Custom label for boundary selector (e.g., "Neighborhoods", "Districts")

Styling

Parameter	Type	Default	Description
boundaryFillColor	string	-	Fill color (hex, e.g., "#ff0000" or "%23ff0000" URL-encoded)
boundaryFillOpacity	number	0	Fill opacity (0-1)
boundaryLineColor	string	-	Line color (hex)
boundaryLineOpacity	number	1	Line opacity (0-1)
boundaryLineWidth	number	2	Line width in pixels

---

Filters

Search

Parameter	Type	Default	Description
search / searchTerm	string	""	Pre-populate the search filter with an initial query

Filter Visibility

Parameter	Type	Default	Description
showFilters	boolean	true	Show filter UI
showVibeFilter	boolean	true	Show vibes filter
showCategoryFilter	boolean	Auto	Show categories filter (auto for places)
showTagFilter	boolean	true	Show tags filter
showSearchFilter	boolean	true	Show search input
showTopLevelFilters	boolean	true	Show filters at top level (vs inside map)
showItemCountOnFilters	boolean	true	Show item counts on filter chips

Filter Behavior

Parameter	Type	Default	Description
filterViewMode	string	"horizontal"	Filter layout: "horizontal" or "tabbed"
filterSelectionMode	string	"auto"	Selection mode: "single", "multiple", "auto"
filterBehavior	string	"trapped"	Navigation behavior when taxonomy filters are passed (see below)
multiSelectTaxonomies	array	[]	JSON array of taxonomy names that allow multi-select
taxonomySortOrder	string	"count"	Sort order per taxonomy (see below)

Taxonomy Sort Order (taxonomySortOrder)

Controls how filter chips are sorted within each taxonomy. Default is count (most items first).

Format: "taxonomy:order,taxonomy:order" — comma-separated key:value pairs

Values:

Value	Description
count	Default. Sort by item count (most items first), then alphabetically
alpha	Alphabetical sorting (theme order → color → A-Z)

Examples:

# All taxonomies alphabetical
taxonomySortOrder=vibes:alpha,categories:alpha,tags:alpha

# Categories by count, vibes alphabetical
taxonomySortOrder=categories:count,vibes:alpha

# Just change tags to alphabetical (others stay as count)
taxonomySortOrder=tags:alpha

Filter Behavior Values (filterBehavior)

Controls how users can navigate taxonomy hierarchies when a taxonomy filter is passed via URL with strictFilter=true.

Value	Description
trapped	Default. User is locked within the passed taxonomy. Only the passed category/vibe/tag and its children are shown. User cannot navigate to parent/sibling taxonomies.
selected	The passed filter is pre-selected, but user can deselect it to see parent-level filters. Allows escaping the passed taxonomy.
open	Current behavior - all taxonomies from returned items are shown, regardless of what was passed.

Important Notes:

• Only applies when strictFilter=true. Without strictFilter, the parameter is ignored and behavior defaults to open.
• If multiple taxonomy values are passed (e.g., ?categories=shop,food), behavior automatically switches to open.
• Applies to all taxonomy types: categories (hierarchical), vibes (flat), and tags (flat).

Date Filters (Events)

Parameter	Type	Default	Description
showDateRangeSelector	boolean	true	Show date range selector (events only)
dateFilterOptions	array	["upcoming","today","weekend","next_week","month"]	Available date filter options

---

Grid/List View

Parameter	Type	Default	Description
initialView	string	"map"	Initial view: "map", "grid", or "list"
gridColumns	number	3	Number of columns in grid view
shownAtStart	number	100	Number of items shown initially
hideSidebar	boolean	false	Hide the sidebar card list (map view only)

---

Card Display

Parameter	Type	Default	Description
cardStyle	string	"list"	Card style variant
showVibesOnCards	boolean	true	Show vibes on cards
showTagsOnCards	boolean	false	Show tags on cards
showAddressOnCards	boolean	true	Show address on cards
subtitleSource	string	"none"	Subtitle content: "none", "category", "address", etc.
showRating	boolean	false	Show ratings on cards
showBookmark	boolean	false	Show bookmark button
openSinglePost	boolean	false	Open item detail page on click

Updates Display

Show offers, specials, clues, and updates from places on cards and in the details panel.

Parameter	Type	Default	Description
showUpdates	boolean	false	Enable updates display on cards and detail panels
updatesDisplayMode	string	"badge"	Card display mode: "badge", "text", or "both"
updatesFilterTypes	string	-	Comma-separated types: Update,Offer,Clue,Sponsor,Special
updatesPosition	string	"under-vibes"	Detail panel position (see below)
updatesExpanded	boolean	true	Updates section expanded by default in detail panels

Update Types:

• Update - General updates and announcements
• Offer - Special offers and discounts
• Clue - Hints and tips (e.g., for scavenger hunts)
• Sponsor - Sponsored content
• Special - Special events or limited-time promotions

Updates Position Values: under-vibes, under-description, before-hours, before-links, after-links

Example - Show Offers Only:

/embed/map-grid?slug=austin&showUpdates=true&updatesFilterTypes=Offer&updatesDisplayMode=badge

---

Theme

Parameter	Type	Default	Description
theme / themeName	string	"default"	Theme slug for styling (e.g., "dark", "minimal")

Themes can provide defaults for many parameters above, reducing URL complexity.

---

Advanced

Parameter	Type	Default	Description
heatmap	boolean	true	Enable heatmap functionality
showExplore	boolean	true	Show explore features
showEvents	boolean	true	Show events on map
showPlaces	boolean	true	Show places on map

---

Not URL-Controllable

The following features require complex configuration that cannot be easily passed via URL parameters:

Complex Objects

• Custom layer paint/layout properties - Layer styling beyond visibility requires nested objects
• Custom GeoJSON boundaries - Must be fetched from API via slug
• Custom combined taxonomies - Complex hierarchical taxonomy configurations
• Custom filters array - Advanced filter configurations with custom logic

Runtime Features

• Selected items state - Managed internally based on user interaction
• Search term state - User input, not initial URL param
• Current view state - Changes as user toggles map/grid
• Focused/hovered items - Managed by user interaction

Theme-Dependent

• Tooltip styling - Controlled by theme's map.boundaryTooltip config
• Clear button styling - Controlled by theme's map.boundaryClearButton config
• Accent colors - Controlled by theme's accent property
• Card themes - Controlled by theme's cards configuration

API-Dependent

• Specific item IDs - Cannot pre-select specific items by ID via URL
• Custom boundary data - Must use slug to fetch boundary from API
• Taxonomy term details - Fetched from API, including colors and hierarchy

---

Example URLs

Basic Places Map

/embed/map-grid?slug=austin&type=places

Events with Filters

/embed/map-grid?slug=dc&type=events&showVibeFilter=true&showDateRangeSelector=true

3D Terrain with Snow

/embed/map-grid?slug=denver&terrain3d=true&terrainExaggeration=1.5&snow=0.7

Clustered Markers with Custom Boundary Style

/embed/map-grid?slug=sf&shouldCluster=true&clusterRadius=50&boundaryLineColor=%23ff6600&boundaryLineWidth=3

Grid View with Custom Columns

/embed/map-grid?slug=la&initialView=grid&gridColumns=4&shownAtStart=20

Rain Effect with Hidden Labels

/embed/map-grid?slug=seattle&rain=0.6&hideLayers=poi-label,road-label

Full Featured Example

/embed/map-grid?slug=nyc&type=places&terrain3d=true&buildings3d=true&shouldCluster=true&showVibesOnCards=true&boundaryLineColor=%234a90e2&boundaryLineWidth=2&markerLabels=featured&theme=dark

---

Notes

1. Boolean parameters accept: true, false, 1, 0, "true", "false"
2. Colors can be passed without the # prefix (e.g., dotsColor=ff0000 or dotsColor=%23ff0000)
3. Arrays are comma-separated strings (e.g., vibes=chill,artsy)
4. Theme defaults - Many parameters have theme-based defaults; only specify to override
5. Parameter precedence: URL params > Theme defaults > Built-in defaults