> 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.

# Getting started

## 1. Get an API key

During the private beta, keys are hand-issued.
[Contact us](mailto:hello@trychora.com) with a one-line description of
what you're building and we'll send one back.

## 2. Make your first call

Weather for a stay in Bath, 14–18 October:

```bash
curl "https://api.trychora.com/v1/chora/weather?lat=51.38&lng=-2.36&start=2026-10-14&end=2026-10-18" \
  -H "Authorization: Bearer $CHORA_API_KEY"
```

You'll get a per-day forecast if the stay is within the 16-day
forecast horizon, or 10-year climatology for the same date range
beyond that. Either way the response shape is identical — the
`mode` field tells you which.

## 3. Try MICHELIN restaurants nearby

```bash
curl "https://api.trychora.com/v1/chora/michelin?lat=51.38&lng=-2.36" \
  -H "Authorization: Bearer $CHORA_API_KEY"
```

Tier-ranked (three-star → Selected), radius-filtered by prestige (a
3-star is worth an hour's drive, a Bib is worth a walk).

## 4. Compose the sections you need

Every Chora endpoint follows the same argument pattern:
`?lat=..&lng=..` for spatial data, plus `&start=&end=` for date-scoped
data. Request them in parallel and drop any that return
`applicable: false`:

```js
const params = new URLSearchParams({ lat, lng, start, end });
const [weather, astronomy, michelin, events] = await Promise.all([
  fetch(`/v1/chora/weather?${params}`,   { headers }),
  fetch(`/v1/chora/astronomy?${params}`, { headers }),
  fetch(`/v1/chora/michelin?lat=${lat}&lng=${lng}`, { headers }),
  fetch(`/v1/chora/events?${params}`,    { headers }),
]).then(rs => Promise.all(rs.map(r => r.json())));

// Render only what's meaningful for this property.
const sections = [weather, astronomy, michelin, events]
  .filter(s => s.applicable);
```

## 5. Or embed the pre-composed widget

No key needed — designed for anonymous embedding on any booking page.
One `<iframe>`:

```html
<iframe
  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"
></iframe>
```

The widget auto-resizes via `postMessage` and renders every section
that's applicable for the coord + dates. Themeable with
`&theme=dark` and `&accent=%23e0245f`.

## Next steps

* [**Chora overview**](/core-concepts/overview) — every endpoint, grouped by purpose, with the shared envelope explained.
* [**Embed the widget**](/widgets/embed-the-widget) — full embed guide with theming and messaging.
* [**Authentication**](/technical-concepts/authentication) — key format and header conventions.
* [**Rate limits**](/technical-concepts/rate-limits) — headers to back off on.
* [API reference](/api-reference) — the full endpoint surface.