---
title: "Get Today Ideas"
method: GET
path: "/api/v1/planner/today"
tags: ["planner"]
---

# Get Today Ideas

`GET /api/v1/planner/today`

## Request

- Base URL: `https://yondry.app` (the document declares no server; this is the origin it was published from)
- URL: `https://yondry.app/api/v1/planner/today`
- Auth: HTTP bearer

Return 1–2 proactive plan ideas tailored to the current time of day,
the user's home location, and their companion preference.

Results are cached per user for 30 minutes so repeated app opens don't
trigger new Claude calls.  Requires the user to have a home location set;
returns an empty list otherwise.

`timezone` is the caller's IANA zone name (e.g. "Europe/London"); when
omitted or unrecognised, the time-of-day bucket falls back to UTC.

## Query parameters

- `timezone` string, nullable

## Response `200`

Successful Response

- TodayIdea[]
  - `label` string, required
  - `summary` string, required
  - `mood` string, required
  - `duration_mins` integer, required
  - `stops` TodayIdeaStop[], required
    - `name` string, required
    - `category` string, required
  - `plan_snapshot` Plan, required: One complete itinerary option returned by Claude Sonnet.
    - `label` string, required
    - `stops` PlanStop[], required
      - `place_id` string, nullable
      - `name` string, required
      - `category` string, required
      - `why` string, required
      - `suggested_duration_minutes` integer, required
      - `is_discovery` boolean
      - `is_meal` boolean
      - `lat` number, nullable
      - `lng` number, nullable
      - `admission_price` string, nullable
      - `alternative_stops` AlternativeStop[]
        - `name` string, required
        - `category` string, required
        - `why` string, required
      - `travel_leg` TravelLegOut
        - `from_stop` string, required
        - `to_stop` string, required
        - `distance_km` number, required
        - `travel_mins` integer, required
        - `travel_mode` string, required
      - `arrival_time` string, date-time, nullable
      - `transition_to_next` TransitionSegment: Travel segment between two consecutive stops within the zone.
        - `mode` string, required
        - `minutes` integer, required
        - `distance_km` number, required
        - `is_estimated` boolean
    - `summary` string, required
    - `conflicts` PlanningConflictOut[]
      - `type` string, required
      - `stop_name` string, required
      - `detail` string, required
      - `suggestion` string, required
    - `total_duration_mins` integer, nullable
    - `plan_notes` string
    - `arrival_segment` JourneySegment: Arrival or return leg between the user's start location and the destination zone.
      - `from_location` string, required
      - `to_location` string, required
      - `mode` string, required
      - `minutes` integer, required
      - `depart_time` string, date-time, required
    - `return_segment` JourneySegment: Arrival or return leg between the user's start location and the destination zone.
      - `from_location` string, required
      - `to_location` string, required
      - `mode` string, required
      - `minutes` integer, required
      - `depart_time` string, date-time, required
    - `buffer_minutes` integer
    - `travel_note` string

## Other responses

- `422`: Validation Error

---

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