---
title: "Get one context-aware recommendation across restaurant / live-music / movie"
method: POST
path: "/surprise-me"
---

# Get one context-aware recommendation across restaurant / live-music / movie

`POST /surprise-me`

## Request

- Base URL: `https://localselections.com/api/v1`
- URL: `https://localselections.com/api/v1/surprise-me`
- Auth: API key in header `X-API-Key`

The same cold-start + personalization logic as the browser's Surprise Me entry point (PROJECT_OVERVIEW.md section 3.3), keyed by the API key owner's own liked history when available. Requires the `surprise_me` scope. Costs 2 units of the key's rate-limit budget per call.

## Request body

- object
  - `hour` integer, required: The caller's local hour — computed server-side time would be in the wrong timezone for most callers.
  - `dayOfWeek` integer, required: 0 = Sunday .. 6 = Saturday, in the caller's local time.
  - `hasLocation` boolean, required
  - `lat` number
  - `lng` number

## Response `200`

One concrete recommendation.

- object
  - `leadCategory` 'restaurant' | 'live-music' | 'movie', required
  - `leadCategoryLabel` string, required
  - `suggestion` object, required: Shape follows the resolved leadCategory — a restaurant/place, a NearbyEvent, or a TrendingTitle.
  - `cuisineMatch` object, nullable
    - `optionId` string
    - `label` string
  - `decisionId` string, nullable

## Other responses

- `400`: The request body failed validation.
- `401`: Missing or invalid API key.
- `403`: The API key does not carry the scope this endpoint requires (see the "Requires the ... scope" note on each path, or call GET /introspect to see a key's real granted scopes).
- `429`: Rate limit exceeded for this API key. The budget is 30 units/60s for keys owned by an unsubscribed account, 120 units/60s for a subscribed account's keys (Stage 60) — shared across every endpoint, but each endpoint spends a different number of units per call rather than always 1 (Stage 104): search/groups_host/groups_join/places/movies cost 1, surprise_me/events cost 2, spin costs 3, bracket costs 4. Call GET /introspect to see a key's real remaining budget before it runs out.
- `502`: An upstream data source failed or returned nothing usable.

---

[API](https://skmtc.dev/localselections/apis/localselections-public-api.md) · [All operations](https://skmtc.dev/localselections/apis/localselections-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/localselections/apis/localselections-public-api/revisions/a24e9598add4?raw)