---
title: "Unfurl Place From Url"
method: POST
path: "/api/v1/places/unfurl"
tags: ["places"]
---

# Unfurl Place From Url

`POST /api/v1/places/unfurl`

## 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/places/unfurl`
- Auth: HTTP bearer

Extract place data from any URL.

Runs the full extraction pipeline (JSON-LD → OG tags → Claude AI →
Google Places) and returns structured place data.

When the pipeline fully resolves a place, the Place + PlaceSource are
saved immediately and `saved_place_id` is set in the response. For
unresolved results only the preview is returned — the client shows a
confirmation card and then POSTs to /places to save.

## Request body

- UnfurlRequest
  - `url` string, required: Any URL to extract place data from
  - `caption_hint` string, nullable: Optional plain-text caption pasted by the user (e.g. from Instagram). Used as primary AI input when the server cannot fetch the page directly.

## Response `200`

Successful Response

- UnfurlResult: Structured result from the link unfurl pipeline. Includes enough data for the mobile app to show a confirmation card before the user commits to saving the place. `resolved` is True when a Google Places ID was found and the full Places API record has been loaded; False means we only have whatever was in the page metadata or AI extraction. `paywalled` is True when the pipeline detected a paywall / subscriber gate and could not extract meaningful place data. `extracted_places` is populated when the AI step found more than one distinct place in the page content, enabling the multi-place checklist UI. Empty list otherwise.
  - `source_url` string, required
  - `resolved` boolean, required
  - `paywalled` boolean
  - `name` string, nullable
  - `address` string, nullable
  - `lat` number, nullable
  - `lon` number, nullable
  - `category` string, nullable
  - `notes` string, nullable
  - `thumbnail_url` string, nullable
  - `caption_excerpt` string, nullable
  - `google_place_id` string, nullable
  - `saved_place_id` string, nullable
  - `extracted_places` PlaceData[]
    - `name` string, required
    - `address` string, nullable
    - `lat` number, nullable
    - `lon` number, nullable
    - `category` string, nullable
    - `notes` string, nullable
    - `google_place_id` string, nullable

## 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)