---
title: "Scout Destination Areas"
method: POST
path: "/api/v1/planner/scout-destinations"
tags: ["planner"]
---

# Scout Destination Areas

`POST /api/v1/planner/scout-destinations`

## 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/scout-destinations`
- Auth: HTTP bearer

Propose 2-3 candidate day-trip destination areas for a discovery query.

Extracts structured intent (Claude Haiku), then calls Claude Sonnet to
scout areas that fit the user's discovery constraints. Each candidate is
geocoded server-side so the client can pass zone_lat / zone_lon directly
to POST /planner/query without an extra round-trip.

Typical flow:
  1. User types "something coastal and family-friendly, not too far"
  2. Client calls POST /planner/scout-destinations
  3. User picks a candidate (e.g. Brighton)
  4. Client calls POST /planner/query with zone_lat / zone_lon / zone_name

## Request body

- ScoutRequest: Request body for POST /planner/scout-destinations.
  - `query` string, required
  - `origin_lat` number, nullable
  - `origin_lon` number, nullable
  - `radius_km` number
  - `departure_time` string, date-time, nullable

## Response `200`

Successful Response

- ScoutResponse: Response for POST /planner/scout-destinations.
  - `candidates` ScoutCandidate[], required
    - `name` string, required
    - `one_line_pitch` string, required
    - `character_tags` string[]
    - `travel_minutes` integer, required
    - `saved_places_in_area` string[]
    - `why_this_fits` string, required
    - `caveats` string
    - `zone_lat` number, nullable
    - `zone_lon` number, nullable
  - `reasoning_summary` string
  - `fewer_candidates_reason` string
  - `intent` PlannerIntent, required: Structured intent extracted from a free-text query by Claude Haiku.
    - `moods` string[]
    - `place_types` string[]
    - `duration_hours` number, nullable
    - `companions` string[]
    - `time_of_day` string, nullable
    - `budget` string, nullable
    - `excluded_place_types` string[]
    - `prefer_discovery` boolean
    - `vibe_conflicts` string[]
    - `planning_mode` union
      - 'local' | 'known_day_trip' | 'discovery_day_trip' | 'away_trip'
      - string
    - `destination` string, nullable
    - `discovery_constraints` DiscoveryConstraints: Spatial/vibe constraints when the user wants us to find a destination.
      - `max_travel_minutes` integer, required
      - `vibe_keywords` string[]
      - `must_haves` string[]
      - `exclusions` string[]
    - `start_location_type` union
      - 'home' | 'custom' | 'current_location' | 'future_location'
      - string
    - `arrival_transport` string, nullable
    - `local_transport` string, nullable
    - `duration_minutes` integer, nullable
    - `start_time` string, date-time, nullable
    - `must_include_meal` boolean
    - `constraints_inferred` string[]
    - `ambiguity_flags` string[]
    - `first_time_visitor` boolean, nullable
    - `named_landmarks` 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)