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). Aliases: `editorial_category`, `editorialCategory`.
`featured`	boolean	`false`	When `true`, only show featured places/events
`dist` / `radius`	number	-	Radius in meters for proximity (geo-distance) search. Requires `latitude` + `longitude` to take effect.
`latitude` / `lat`	number	-	Center latitude for proximity search. Only used when `longitude` and `dist`/`radius` are also set.
`longitude` / `lng`	number	-	Center longitude for proximity search. Only used when `latitude` and `dist`/`radius` are also set.
`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) | | subtitleSources | string | - | Comma-separated list of sources to combine for the first subtitle when subtitleSource=custom. First-subtitle analog of subtitle2Sources — same token vocabulary, joined with •. | | 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" | | showTierBadge | boolean | false | Show the membership-tier badge on cards (e.g. "Premium"). | | usePillLayout | boolean | true | For multi-day events, render the date badge as a horizontal pill (date range). Set false for the stacked calendar-style badge. | | ongoingEventShowNow | boolean | false | For ongoing events (started in the past, still running), show the start as "Now" instead of today's date. | | timeBadges | string | - (off) | Comma-separated list of time-relative event badges to enable on cards (e.g. today,tonight,weekend). Off by default. Only the single highest-precedence matching badge renders per card. Falls back to theme.cards.timeBadges. See values below. |

Time Badges (`timeBadges`)

Opt-in, time-relative badges for event cards, computed from each event's start (and optional end) relative to "now". Pass a comma-separated list of types; unknown values are ignored. Only the single highest-precedence match renders per card.

Value	Badge label	Matches when…
`ongoing`	"Ongoing"	A multi-day event (≥ 24h span) is currently running
`happening-now`	"Happening Now"	The event is currently live (start ≤ now ≤ end; requires an end date)
`tonight`	"Tonight"	Starts today, at or after 5pm
`today`	"Today"	Starts today
`tomorrow`	"Tomorrow"	Starts tomorrow
`weekend`	"This Weekend"	Starts during the upcoming Sat–Sun window
`this-week`	"This Week"	Starts within today → next 7 days

Precedence is highest-first in the order above — e.g. a 7pm event tonight shows "Tonight" rather than "Today" when both are enabled. Labels can be overridden per theme via theme.cards.timeBadges.

Example: timeBadges=happening-now,today,tonight,weekend

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
`showRecurrenceBadge`	boolean	`false`	Show the recurrence label pill (e.g. "Weekly Wed - Sun") on event cards
`hideRangedEvents`	boolean	`false`	Hide "ranged" events — those with a duration longer than 24 hours (e.g. multi-day festivals, ongoing exhibits).

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

Sticky-Header Offset (`scrollToTopOffset`)

Applies to data-resize="true" embeds. When a visitor clicks a carousel card, the single place/event opens in place and load.js scrolls the host page back up so the item's title/hero is in view. If your host page has a sticky or fixed header, the embed's top edge lands underneath it and the title stays covered. Set scrollToTopOffset to your header's height (px) to leave that much gap above the embed after the scroll, so the title clears the header.

Parameter	Type	Default	Description
`scrollToTopOffset`	number	`0`	Extra pixels of gap left above the embed when it scrolls to the top after opening a single item. Set to your sticky header's height. Non-negative integers only; `0` rests the embed flush against the viewport top (the original behavior).

Where it's read: Put scrollToTopOffset in the embed's URL params, alongside the others — it works on a proxied api.vibemap.com/list/<slug> short link too, because the embed reads it inside the iframe and forwards it to the loader over postMessage. The value is retained across the in-embed card→single navigation, so you set it once on the carousel embed and it also applies to the single/similar-item views opened from it. (For host-side configuration load.js also honors it on the <script>'s data-url query or a data-scroll-to-top-offset="100" attribute.)

/embed/carousel?slug=austin&scrollToTopOffset=96

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;
    }
  }
});

Message Origin

Embed messages may arrive from either of these origins:

https://web.vibemap.com — when the embed is loaded directly
https://api.vibemap.com — when the embed is loaded via a Vibemap list link (/list/<slug>) or short link (/s/<slug>), which reverse-proxies the embed page through the API host

Parent-window listeners should filter by payload (event.data.embedId and event.data.type) rather than event.origin. The example handler above already follows this pattern.

If you must check event.origin, accept BOTH https://web.vibemap.com AND https://api.vibemap.com.

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​

Time Badges (timeBadges)​

Rating Parameters​

Bookmark Parameters​

Button Parameters​

Event-Specific Parameters​

Date Boundary​

Past Event Window​

Updates Display​

Behavior Parameters​

Theme Parameter​

Sticky-Header Offset (scrollToTopOffset)​

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​

Message Origin​

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

Time Badges (`timeBadges`)

Rating Parameters

Bookmark Parameters

Button Parameters

Event-Specific Parameters

Date Boundary

Past Event Window

Updates Display

Behavior Parameters

Theme Parameter

Sticky-Header Offset (`scrollToTopOffset`)

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

Message Origin

Embedding

Basic iframe Embed

With Custom Header

Responsive Embed

Notes