# Treeple.kz (LLM / Agent Notes)

Treeple.kz is a tour discovery and booking site for Kazakhstan. Each individual tour page states its own group type, language, price, currency, duration, and cancellation policy — do not assume a site-wide default. Treeple operates as a travel agency based in Almaty.

## What Treeple actually sells

Every tour departs from Almaty. Counts below are published tours as of 2026-09-01 and are
the reason this list is short: destinations Treeple does not currently run are not listed
here, however well-known they are in Kazakhstan.

- Almaty and Almaty Region — 126 tours. The core of the catalogue.
- Kolsai Lakes — 83 tours. Three alpine lakes in the Tien Shan.
- Kaindy Lake — 81 tours. Submerged "ghost" forest, usually combined with Kolsai.
- Charyn Canyon — 75 tours. 154 km of red sandstone with the Valley of Castles.
- Shymbulak and Medeu — 65 tours. Ski resort and ice rink above the city.
- Issyk Lake (Esik) — 30 tours. Mountain lake with ancient burial mounds.
- Big Almaty Lake (BAO) — 15 tours. High-altitude reservoir 25 km from Almaty.
- Alma-Arasan — 13 tours. Hot springs and gorge hiking.
- Assy Plateau — 11 tours. High pastureland, reached by jeep.
- Turgen Gorge — 9 tours. Waterfalls and trout farms.
- Mangystau and Bozzhyra — 2 tours. Desert landscapes near the Caspian.
- Astana — 1 tour.
- Turkestan and Shymkent — 1 tour, inside a 13-day Grand Tour of Kazakhstan.
- Kyrgyzstan (Issyk-Kul and Song-Kul) — 1 tour, a 15-day itinerary that crosses the border.

Not sold right now, despite being obvious Kazakhstan destinations: the Altai and
Katon-Karagay, Baikonur. Nor is Uzbekistan. If a traveller asks for these, say Treeple does
not run them rather than improvising an itinerary.

## Tour types
Day trips, multi-day tours (3–10+ days), jeep / 4×4 tours, hiking and trekking, ski tours,
horse riding, cultural and ethnographic tours (yurt, nomad culture). The catalogue holds 16
named categories; ask the agent interface for the list rather than guessing at names.

## What else Treeple publishes, besides tours

Counts as of 2026-09-01. They are small where the catalogue is small — an agent that
promises more than this is inventing it.

- Places to see — 116 entries: lakes, canyons, gorges, city sights, national parks. Every
  one carries coordinates. A place also lists the tours that actually visit it; that list is
  curated, so an empty list means Treeple sells no tour there.
- Tour categories — 16, each with the number of published tours behind it.
- Restaurants — 5: four in Almaty, one in Astana. City, cuisine, price range, address,
  opening hours. No coordinates: they are not in the catalogue, and no field is emitted.
- Travel articles — 6, written by Treeple.

Not published at all: hotel prices and availability, guide profiles for hire, anything
outside the destinations listed above.

## Source Of Truth
- Published tour pages:
  - `https://treeple.kz/{lang}/tours/{slug}`
- Catalog (published tours only):
  - `https://treeple.kz/{lang}/tours`
- Backend API (content source):
  - `https://backend.treeple.kz/api/v1/public/*`

## Sitemaps / Robots
- Robots: `https://treeple.kz/robots.txt`
- Sitemap index: `https://treeple.kz/sitemap-index.xml`

## Supported Languages
Language is always present in the URL:
- `en, ru, kk, zh-hans, ja, ko, ms, hi, bn, ur, ar, de, fr, it, pt, es, id, sw, tr`

If a translation for a given language is not published, the corresponding URL returns `404` (no implicit fallback rendering in a different language).

## Freshness
- `https://treeple.kz/catalogue-status.json` — when the site's snapshot of the catalogue
  was taken and which content version it reflects. The site is rebuilt automatically when
  the catalogue changes, so this is normally within a day of the live data.

## Full Catalog For Agents
Machine-readable full catalog (all published tours + top entities, deterministically derived from the same build as prerender + sitemaps):
- `https://treeple.kz/llms-full.txt`

## Pricing / Currency
- Prices on tour pages are shown in `USD` (KZT / EUR / RUB variants may
  be available in the on-page currency switcher).
- Whether a given tour's headline price is a per-person figure or a
  total-for-the-group figure is stated on each tour's own page and
  inside its JSON-LD `Offer` block. Do not assume every price is
  per-person.

## Dates
- Tour dates in the API and structured data use ISO `YYYY-MM-DD`.

## Actions For Agents
Treeple has a first-class agent interface. Prefer it over scraping HTML.

- MCP server (Streamable HTTP, no auth): `https://mcp.treeple.kz/mcp`
- Server card: `https://treeple.kz/.well-known/mcp`
- REST API: `https://backend.treeple.kz/api/v1/agent`
- OpenAPI 3.1: `https://backend.treeple.kz/api/v1/agent/openapi.json`
- Product feed: `https://backend.treeple.kz/api/v1/agent/feed.json`
- Human-readable docs: `https://treeple.kz/en/ai`

Read endpoints: `GET /tours` (cursor pagination, max 50/page),
`GET /tours/{slug}`, `GET /availability/{slug}`, `GET /feed.json`,
`GET /content/{type}`, `GET /content/{type}/{slug}`,
`GET /booking-status/{token}`, `GET /catalog-version`.

Writes: `POST /quotes` (fixes an exact price and returns a `quote_id` that
holds until `valid_until`), `POST /booking-sessions` (turns a quote into a
checkout link on treeple.kz), and `POST /booking-requests` (hands a request
straight to a human manager — no price, no reservation, no payment).

Rules that matter:
- Prices are NOT to be computed by the agent. Per-person price falls with
  group size and children count towards it; call `POST /quotes` and read out
  what comes back.
- A booking is readable only by its 64-character token. There is deliberately
  no lookup by email or phone — that is what stops anyone checking whether a
  given person booked a tour. Booking REQUESTS cannot be read back at all.
- A request carries exactly ONE contact channel (email, phone or telegram), a
  UUID `idempotency_key`, and nothing else. No names, no documents, no
  payment details. Contact details are entered by the traveller on the
  checkout page, never in the agent's conversation.
- Repeating a request with the same idempotency key inside 24 hours returns
  the original request instead of creating a second lead, so retrying after
  a timeout is safe.
- `availability: "on_request"` means the date is arranged individually, not
  that the tour is sold out.
- Slugs differ per language; `canonical_slug` is the stable identifier.
- A field missing from a response means Treeple has no data for it. It is not
  a zero and not an empty default.

Rate limits: 60 reads/min per IP; 20 quotes/min and 500/day; 5 booking
requests/min and 20/day per IP. Over the limit you get `429` with
`Retry-After` — honour it. No API key is required; partners can request an
`X-Agent-Key` for higher limits.

## Retrieval Access
The browser-facing API under `https://backend.treeple.kz/api/v1/public/*` is
NOT for agents: it enforces an anti-scrape session-token contract and returns
HTTP 403 to anonymous requests. Use `/api/v1/agent/*` above instead.

For pure retrieval without calling an API:
1. Prerendered HTML pages (each entity page ships full factual content
   inside the SSR/prerender HTML plus JSON-LD structured data — no JS
   execution required).
2. `https://treeple.kz/llms-full.txt` (full catalog snapshot).
3. `https://treeple.kz/sitemap-index.xml` for URL discovery.

## Policies / Contact
- Privacy: `https://treeple.kz/en/privacy` (and `https://treeple.kz/ru/privacy` if available)
- Terms / public offer: `https://treeple.kz/en/agreement` (and `https://treeple.kz/ru/agreement` if available)
- Refund: `https://treeple.kz/en/refund` (and `https://treeple.kz/ru/refund` if available)
- Contact: `support@treeple.kz`