Carousel URL Parameters

The /embed/carousel endpoint renders a CardCarousel component that displays places or events in a horizontally scrollable carousel layout.

Base URL

/embed/carousel?slug=<boundary-slug>

Required Parameters

Parameter	Type	Description
`slug` OR `boundary`	string	Location boundary slug (e.g., "austin", "sf", "denver")
`list`	string	Alternative: List slug that provides configuration from Lists API

Note: Either slug/boundary OR list must be provided. When using list, if the list has an associated organization, that organization's boundary will be used automatically.

Content & Data Parameters

Parameter	Type	Default	Description
`type`	string	`"places"`	Content type: `"places"` or `"events"`
`vibes`	string	-	Comma-separated vibe filters (e.g., `"chill,artsy"`)
`categories`	string	-	Comma-separated category filters
`tags`	string	-	Comma-separated tag filters
`editorial_categories`	string	-	Editorial category filters (always applied server-side)
`featured`	boolean	`false`	When `true`, only show featured places/events
`dist` / `radius`	number	-	Radius in meters for proximity search
`hideNoImageItems`	boolean	`false`	Hide items without images
`tiers`	string	-	Filter by membership tier slugs. Comma-separated (e.g., `"basic,premium"`). Use `"non-member"` for items with no tier.
`strictFilter`	boolean	`false`	When `true`, taxonomy filters are applied server-side
`ordering` / `sort`	string	`"-score_combined"`	Sort order for results (see below)

Sort Order (`ordering` / `sort`)

Controls how places are sorted in the carousel.

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)

Carousel Display Parameters

Parameter	Type	Default	Description
`columns` / `gridColumns`	number	`4`	Number of visible slides/cards
`header`	string	-	Optional header text above the carousel

Card Display Parameters

Parameter	Type	Default	Description
`showVibesOnCards`	boolean	`true`	Show vibes on cards
`showTagsOnCards`	boolean	`false`	Show tags on cards
`showCategoriesOnCards`	boolean	`false`	Show categories on cards
`showDescription`	boolean	`false`	Show description on cards
`showAddressOnCards`	boolean	`true`	Show address on cards

Deprecated: Use subtitle2Source=address&subtitle2Position=below-title instead.

| subtitleSource | string | "none" | Source for card subtitle: "none", "category", "address", etc. | | subtitlePosition | string | "above-title" | Subtitle position: "above-title" or "below-title" | | subtitle2Source | string | content-type default | Data source for the second subtitle. Default: places="address", events="none". Options: "none", "category", "tag", "vibe", "address", "venue", "date" (date only, e.g. "Jun 15th"), "start_date_time" (date + time, e.g. "Jun 15th • 7:00 PM"), "price", "custom" (combine multiple — see subtitle2Sources) | | subtitle2Sources | string | - | Comma-separated list of sources to combine when subtitle2Source=custom. Each token uses the same vocabulary as subtitle2Source (e.g. category, venue, start_date_time). Empty values are skipped; the rest are joined with •. Example: subtitle2Source=custom&subtitle2Sources=venue,start_date_time → "Great Hall • Jun 15th • 7:00 PM" | | subtitle2Position | string | "below-title" | Position of the second subtitle: "above-title" or "below-title" |

Rating Parameters

Parameter	Type	Default	Description
`showRating`	boolean	`false`	Show ratings on cards
`ratingShape`	string	`"star"`	Rating shape: `"star"` or `"dot"`
`ratingDisplayStyle`	string	`"both"`	Display style: `"stars"`, `"number"`, or `"both"`
`ratingPosition`	string	`"below-title"`	Position: `"above-title"`, `"below-title"`, `"below-address"`, `"next-to-category"`
`ratingStarSize`	number	`16`	Size of rating stars in pixels
`ratingStarColor`	string	`"#FFD700"`	Color of rating stars (hex)
`showRatingCount`	boolean	`true`	Show the number of ratings

Bookmark Parameters

Parameter	Type	Default	Description
`showBookmark`	boolean	`false`	Show bookmark button on cards
`bookmarkIcon`	string	`"star"`	Icon type: `"bookmark"`, `"heart"`, or `"star"`
`bookmarkIconColor`	string	`"#FF0000"`	Color of bookmark icon (hex)
`smartCrop`	boolean	`true`	ImageKit AI smart crop (`fo-auto`). Set `false` for deterministic center crop
`linkToExternalUrl`	boolean	`false`	Open each card's source URL (event source, place website) in a new tab instead of the internal single-post page. Falls back to the internal permalink when no source URL is set.

Button Parameters

Parameter	Type	Default	Description
`showButton`	boolean	`false`	Show action button on cards
`buttonText`	string	-	Custom text for the button

Event-Specific Parameters

Parameter	Type	Default	Description
`groupRecurringEvents`	boolean	`false`	Group recurring events to show only next occurrence

Recurring Event Behavior: When groupRecurringEvents=true, events from a recurring series are grouped together, showing only the next occurrence with a badge indicating more dates are available. Clicking the recurring badge navigates to the event series page (/event-series/{id}) where all occurrences can be viewed.

Date Boundary

Hard date limits that exclude events outside the range, regardless of other filters.

Parameter	Type	Default	Description
`dateBoundaryStart`	string	-	Events before this date are excluded. Accepts `yyyy-MM-dd` or relative offset.
`dateBoundaryEnd`	string	-	Events after this date are excluded. Accepts `yyyy-MM-dd` or relative offset.

Relative offset format: +Nd (days), +Nm (months), +Ny (years). Negative values work too (-7d = 7 days ago). The offset is computed fresh on each page load relative to the current date.

Examples:

# Only show events in the next 14 days
/embed/carousel?slug=austin&type=events&dateBoundaryEnd=%2B14d

# Next 3 months of events
/embed/carousel?slug=austin&type=events&dateBoundaryEnd=%2B3m

# Events between specific dates
/embed/carousel?slug=austin&type=events&dateBoundaryStart=2026-06-01&dateBoundaryEnd=2026-09-01

Note: The + character must be URL-encoded as %2B in query strings.

Past Event Window

Controls how long after an event's end time it remains visible in the carousel. Default keeps every event visible for 90 minutes after it ends, so events with identical start/end times don't disappear the instant they begin.

Parameter	Type	Default	Description
`pastWindow`	integer (minutes)	`90`	Minutes after `end_date` that an event remains eligible. `0` cuts at end. `1440` shows for 1 day. `10080` shows for a week. Overridden by `pastCutoff` if both are set.
`pastCutoff`	ISO 8601 datetime	–	Absolute floor — only events with `end_date >= pastCutoff` are shown, e.g. `2026-06-01T00:00:00`. Site-local time. Overrides `pastWindow` when set.

Examples:

# Show events for 6 hours after they end
/embed/carousel?slug=austin&type=events&pastWindow=360

# Show all events from the past week onward
/embed/carousel?slug=austin&type=events&pastWindow=10080

# Show every event ending on/after June 1, 2026
/embed/carousel?slug=austin&type=events&pastCutoff=2026-06-01T00:00:00

Updates Display

Parameter	Type	Default	Description
`showUpdates`	boolean	`false`	Enable updates display on cards
`updatesDisplayMode`	string	`"badge"`	Display mode: `"badge"`, `"text"`, or `"both"`
`updatesFilterTypes`	string	-	Comma-separated types: `Update,Offer,Clue,Sponsor,Special`

Behavior Parameters

Parameter	Type	Default	Description
`autoScrollSpeed`	number	`0`	Auto-scroll interval in ms (500–30000). `0` or absent = off.
`randomize`	boolean	`false`	Shuffle card order on each page load

Auto-scroll behavior: When enabled, the carousel automatically advances slides at the specified interval. It pauses when the user hovers over or interacts with the carousel, then resumes. Values below 500ms (except 0) are ignored.

Examples:

# Auto-scroll every 3 seconds
/embed/carousel?slug=austin&autoScrollSpeed=3000

# Randomized order with auto-scroll
/embed/carousel?slug=austin&autoScrollSpeed=4000&randomize=true

# Just randomized order, no auto-scroll
/embed/carousel?slug=austin&randomize=true

Theme Parameter

Parameter	Type	Default	Description
`theme` / `themeName`	string	`"default"`	Theme slug for styling

Example URLs

Basic Places Carousel

/embed/carousel?slug=austin&type=places

Events Carousel

/embed/carousel?slug=dc&type=events&groupRecurringEvents=true

Carousel with Custom Columns

/embed/carousel?slug=la&columns=5

List-Based Carousel

/embed/carousel?list=my-curated-list&columns=4

Carousel with Header

/embed/carousel?slug=sf&header=Featured%20Places

Filtered by Editorial Category

/embed/carousel?slug=austin&editorial_categories=best-coffee-shops

Featured Items Only

/embed/carousel?slug=austin&type=events&featured=true

With Ratings Displayed

/embed/carousel?slug=denver&showRating=true&ratingDisplayStyle=both&ratingPosition=below-title

With Bookmarks and Buttons

/embed/carousel?slug=nyc&showBookmark=true&bookmarkIcon=heart&showButton=true&buttonText=View%20Details

Hide Items Without Images

/embed/carousel?slug=sf&hideNoImageItems=true

Full Featured Example

/embed/carousel?slug=nyc&type=places&columns=4&header=Top%20Spots&showVibesOnCards=true&showAddressOnCards=true&showRating=true&hideNoImageItems=true&theme=default

PostMessage Events

The embed communicates with the parent window via postMessage:

Event Type	Description	Data
`"card-clicked"`	User clicked a card	`{ embedId: "carousel", data: <item> }`

Example Parent Window Handler

window.addEventListener("message", (event) => {
  if (event.data.embedId === "carousel") {
    switch (event.data.type) {
      case "card-clicked":
        console.log("Card clicked:", event.data.data);
        // Navigate to detail page, open modal, etc.
        break;
    }
  }
});

Embedding

Basic iframe Embed

<iframe
  src="https://vibemap.com/embed/carousel?slug=austin&type=places"
  width="100%"
  height="350"
  frameborder="0"
  style="border: none;"
></iframe>

With Custom Header

<iframe
  src="https://vibemap.com/embed/carousel?slug=austin&header=Discover%20Austin"
  width="100%"
  height="400"
  frameborder="0"
  style="border: none;"
></iframe>

Responsive Embed

<div style="width: 100%; max-width: 1200px; margin: 0 auto;">
  <iframe
    src="https://vibemap.com/embed/carousel?slug=austin"
    width="100%"
    height="350"
    style="border: none;"
  ></iframe>
</div>

Notes

The carousel automatically adjusts the number of visible cards based on container width
Navigation arrows appear only when there are more items than can fit on screen
Cards are displayed in vertical orientation with a consistent "basic" style variant
For events, enabling groupRecurringEvents will show only the next upcoming occurrence of each recurring event series

Base URL​

Required Parameters​

Content & Data Parameters​

Sort Order (ordering / sort)​

Carousel Display Parameters​

Card Display Parameters​

Rating Parameters​

Bookmark Parameters​

Button Parameters​

Event-Specific Parameters​

Date Boundary​

Past Event Window​

Updates Display​

Behavior Parameters​

Theme Parameter​

Example URLs​

Basic Places Carousel​

Events Carousel​

Carousel with Custom Columns​

List-Based Carousel​

Carousel with Header​

Filtered by Editorial Category​

Featured Items Only​

With Ratings Displayed​

With Bookmarks and Buttons​

Hide Items Without Images​

Full Featured Example​

PostMessage Events​

Example Parent Window Handler​

Embedding​

Basic iframe Embed​

With Custom Header​

Responsive Embed​

Notes​

Base URL

Required Parameters

Content & Data Parameters

Sort Order (`ordering` / `sort`)

Carousel Display Parameters

Card Display Parameters

Rating Parameters

Bookmark Parameters

Button Parameters

Event-Specific Parameters

Date Boundary

Past Event Window

Updates Display

Behavior Parameters

Theme Parameter

Example URLs

Basic Places Carousel

Events Carousel

Carousel with Custom Columns

List-Based Carousel

Carousel with Header

Filtered by Editorial Category

Featured Items Only

With Ratings Displayed

With Bookmarks and Buttons

Hide Items Without Images

Full Featured Example

PostMessage Events

Example Parent Window Handler

Embedding

Basic iframe Embed

With Custom Header

Responsive Embed

Notes