> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trychora.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trychora.com/_mcp/server.

# Embed the widget

The Chora widget is a server-rendered HTML card designed to sit on
a property booking page. No API key, no JavaScript framework, works
inside any iframe.

Two display modes, and full control over which tiles appear.

## Modes

#### Inline

Full card that sits in the page flow — usually below the gallery
or beside the booking widget. Auto-resizes to its content height.

#### Popup / corner

Compact card that floats in a bottom-right corner. Ideal for
always-visible context without displacing page content.

## Inline

```html
<iframe
  class="chora-embed"
  src="https://api.trychora.com/v1/chora?lat=51.38&lng=-2.36&start=2026-10-14&end=2026-10-18&place=The%20Royal%20Crescent"
  width="100%"
  height="800"
  frameborder="0"
  style="border: 0; border-radius: 14px;"
></iframe>

<script src="https://api.trychora.com/embed.js" async></script>
```

`embed.js` handles the shimmer skeleton and auto-resize for you. If
you'd rather wire it yourself, see [Graceful loading](#graceful-loading)
and [Auto-resize](#auto-resize-inline-mode).

## Popup

```html
<iframe
  class="chora-embed"
  src="https://api.trychora.com/v1/chora?lat=51.38&lng=-2.36&start=2026-10-14&end=2026-10-18&mode=corner"
  width="360"
  height="480"
  frameborder="0"
  style="position: fixed; right: 24px; bottom: 24px; border: 0; border-radius: 14px; box-shadow: 0 12px 32px rgba(0,0,0,0.15);"
></iframe>

<script src="https://api.trychora.com/embed.js" async></script>
```

## Choose which tiles to show

By default the widget renders every applicable section for the coord
and dates. To limit it, pass `sections=` with a comma-separated list of
tile IDs.

```html
<!-- Just weather + MICHELIN + events -->
<iframe
  src=".../v1/chora?lat=51.38&lng=-2.36&start=...&end=...&sections=weather,michelin,events"
></iframe>
```

**Available tile IDs:**

| ID              | Tile                                   | Notes                        |
| --------------- | -------------------------------------- | ---------------------------- |
| `weather`       | Weather forecast for the stay          | Forecast or climatology      |
| `astronomy`     | Sunrise and sunset                     |                              |
| `marine`        | Sea conditions                         | Coastal only                 |
| `snow`          | Snowfall + depth                       | Alpine only                  |
| `transport`     | Nearest airports + directions          |                              |
| `events`        | Ticketed events                        | Live inventory               |
| `festivals`     | Iconic annual celebrations             | Curated                      |
| `attractions`   | Bookable tours + attractions           | Affiliate deep-links         |
| `wildlife`      | Seasonal species                       | Citizen-science observations |
| `michelin`      | MICHELIN restaurants                   | Tier-ranked                  |
| `gardens`       | RHS Partner Gardens                    | UK only, 60 km radius        |
| `nationaltrust` | National Trust properties              | UK only, 60 km radius        |
| `ntwalks`       | National Trust walks                   | UK only, 40 km radius        |
| `museums`       | UK museums (Mapping Museums)           | UK only, 40 km radius        |
| `artgalleries`  | Art galleries (arts subset of museums) | UK only, 40 km radius        |
| `heritage`      | UNESCO World Heritage Sites            | Global, 200 km radius        |
| `darksky`       | Dark Sky Places                        | Global, 200 km radius        |

Order is preserved: `sections=michelin,weather,events` renders in that
order. Tiles that would return `applicable: false` for the coord are
still dropped, even if requested.

## Query parameters

| Param      | Required | Default     | Description                                                                        |
| ---------- | -------- | ----------- | ---------------------------------------------------------------------------------- |
| `lat`      | Yes\*    | —           | Property latitude, `-90` to `90`                                                   |
| `lng`      | Yes\*    | —           | Property longitude, `-180` to `180`                                                |
| `postcode` | Yes\*    | —           | UK postcode, e.g. `BA1 5LR`. Alternative to `lat`+`lng`; resolved via postcodes.io |
| `start`    | Yes      | —           | Stay start date, `YYYY-MM-DD`                                                      |
| `end`      | Yes      | —           | Stay end date (inclusive), `YYYY-MM-DD`                                            |
| `place`    | No       | auto        | Human-readable property/location name                                              |
| `mode`     | No       | `inline`    | `inline` (full card) or `corner` (popup)                                           |
| `sections` | No       | all         | Comma-separated tile IDs from the table above                                      |
| `theme`    | No       | `light`     | `light` or `dark`                                                                  |
| `accent`   | No       | site accent | Hex color for links + accents (with or without `#`)                                |

\* Provide either `lat`+`lng` or `postcode`. If both, `lat`+`lng` win.

## Locating by postcode

If your CMS stores addresses rather than coordinates, use `postcode`
instead of `lat`/`lng` and let Chora geocode server-side:

```html
<iframe
  src="https://api.trychora.com/v1/chora?postcode=BA1%205LR&start=2026-10-14&end=2026-10-18"
></iframe>
```

Coverage is UK-only (postcodes.io). The resolved coord is the postcode
unit centroid — accurate to \~100 m in urban areas, \~500 m rural. Good
enough for every radius tile (defaults are ≥ 20 km). When `postcode`
is used, JSON endpoints return a `location.resolved_from` block so you
can echo the admin district or region back to the user.

## Auto-resize (inline mode)

The widget posts a `message` event with its own height on load and on
mutation. Wire it up on the host page:

```html
<iframe id="chora" src=".../v1/chora?..." style="width:100%; border:0;"></iframe>

<script>
  window.addEventListener("message", (e) => {
    if (e.data && e.data.type === "chora:height") {
      document.getElementById("chora").style.height = e.data.height + "px";
    }
  });
</script>
```

## Graceful loading

Widget composition takes \~1–2 seconds on a cold request (16 upstream
sources fanned out in parallel; subsequent requests within the minute
are served from cache). Give visitors a placeholder while the first
render is in flight — one `<script>` tag does it:

```html
<iframe
  class="chora-embed"
  src="https://api.trychora.com/v1/chora?lat=51.38&lng=-2.36&start=2026-10-14&end=2026-10-18"
  width="100%" height="800" frameborder="0"
  style="border:0;border-radius:14px"
></iframe>

<script src="https://api.trychora.com/embed.js" async></script>
```

`embed.js` finds every Chora iframe on the page, drops a shimmer
skeleton behind it, fades the widget in the moment its `load` event
fires, and wires up the auto-resize `postMessage`. No CSS to paste,
no wrapper markup, no client framework required. The script is
\~2 KB gzipped and cached for 5 minutes at the edge.

If you'd rather roll your own placeholder — full control over layout
and animation — skip the script tag and inline this pattern:

```html
<div class="chora-wrap" style="position:relative">
  <div class="chora-skeleton" aria-hidden="true"></div>
  <iframe
    src="https://api.trychora.com/v1/chora?..."
    onload="this.style.opacity=1;
            this.previousElementSibling.style.opacity=0"
    style="width:100%;border:0;border-radius:14px;
           opacity:0;transition:opacity 220ms ease-out"
  ></iframe>
</div>

<style>
  .chora-skeleton {
    position: absolute; inset: 0; border-radius: 14px;
    background: linear-gradient(90deg,
      rgba(17,58,144,0.06) 0%,
      rgba(17,58,144,0.14) 50%,
      rgba(17,58,144,0.06) 100%);
    background-size: 200% 100%;
    animation: chora-shimmer 1.4s ease-in-out infinite;
    transition: opacity 300ms ease-out;
  }
  @keyframes chora-shimmer {
    0%   { background-position: 100% 50%; }
    100% { background-position: -100% 50%; }
  }
</style>
```

## Theming

```html
<!-- Dark mode -->
<iframe src=".../v1/chora?...&theme=dark"></iframe>

<!-- Brand accent (URL-encode the # as %23) -->
<iframe src=".../v1/chora?...&accent=%23e0245f"></iframe>
```

## Caching

Widget responses are served with `Cache-Control: public, max-age=60`.
The widget refreshes every minute. Underlying tile data follows each
endpoint's freshness (weather every 10 minutes, MICHELIN monthly).

## Framing policy

The widget sets `Content-Security-Policy: frame-ancestors *`. It
embeds anywhere. If you're on a site with a strict CSP, add
`https://api.trychora.com` to your `frame-src`.