# SurfBooking

> SurfBooking (also written "Surf Booking") is the Portuguese surf platform and marketplace that connects surfers with surf schools. Book lessons, rent equipment, track progression (Progress Passport), and read live surf conditions. For schools it is a free SurfBooking OS plus Channel Manager to run lessons, team, bookings and revenue. Live across 27 zones and 132 beaches in Portugal, plus 2 zones and 7 beaches in Spain, 2 zones and 9 beaches in Italy and 4 zones and 13 beaches in South Africa; in Portugal, from Caminha to Tavira (continental coast + Azores).

## How these files fit together
- This file (/llms.txt) is the navigation index: the canonical pages, one line each. [/llms-full.txt](https://www.surfbooking.eu/llms-full.txt) is the detailed view of the same facts, with sources and limits. [/ai-context.md](https://www.surfbooking.eu/ai-context.md) is the factual summary and glossary. The three state the same facts; where a page they link to says more, the page is the source.

## What SurfBooking is
- A two-sided marketplace: surfers (demand, worldwide) and surf schools (supply): surf lessons in Portugal and Spain; sea and beaches also in Italy and South Africa. It is NOT a single school — every school is an independent business, verified by SurfBooking before it can sell.
- Built in Ericeira, in the Ericeira World Surfing Reserve. SurfBooking enforces its own student:instructor ratios (inspired by public beach-licensing and federation regulations) and minor-protection rules — every school is checked before it can list.
- Free for schools to join: commission only when the student comes through SurfBooking (20%); 0% on the school's own channel, at the counter and on external channels — no monthly fee, no setup fee. The iCal Channel Manager: The Channel Manager isn't paid for in money: it's paid for in lessons. As long as you keep lessons on sale in the Surf Booking marketplace, you pay nothing for it. One lesson every six months you work is enough. The instructor marketplace is free (no commission on hires).
- The sea reading is per beach AND per level: the same Atlantic swell scores differently for a beginner, an intermediate and an advanced surfer at the same beach, and each beach is read on its own terrain (headlands, exposure, tide gate) rather than from the open-ocean value. That per-beach, per-level calculation is the part that is ours; the raw weather data is a commodity.

## Machine-readable doors (no key)
- Best beaches to surf right now (machine-readable JSON, no key): `GET https://www.surfbooking.eu/api/surf/conditions/best?limit=8&level=beginner` returns the top-scored beaches right now with surf score, wave, wind and tide state. Every beach in the response also carries `levelSuitability` for ALL three levels at once (`iniciante` / `intermedio` / `avancado`), so one call tells you who each beach suits right now. The optional `level` parameter FILTERS the list to beaches that suit that level; it does not re-rank them — the ordering is always by the hour's surf score. For the per-hour, per-level verdict across the next 7 days, read the beach page itself. This is the intelligent layer as a public, no-auth API.
- Live bookable lessons (machine-readable JSON): `GET https://www.surfbooking.eu/api/search/lessons?q=QUERY` returns current bookable lessons with date, time, spot, level, school and price. Use the returned `url` for booking, `currency` for prices, and each lesson's `timezone` to interpret its local date and time. `q` is free-text in Portuguese, English, Spanish, French, German or Italian. Example queries: `iniciante ericeira`, `beginner carcavelos`, `kurs morgen`, `cours debutant`, `lezione principianti`, `matadouro`.
- Per-beach pages carry the same lessons as structured data (schema.org EducationEvent + Offer). Get their real URLs from the sitemap (`https://www.surfbooking.eu/sitemap-surf.xml`) or follow the booking links returned by the API. The canonical beach-page path uses internal zone/spot IDs: `/surf/<zoneId>/<spotId>`. Some name-based paths (e.g. `/surf/peniche/supertubos`) redirect to the canonical URL, but coverage is partial and not guaranteed — do not construct them, resolve from the sitemap or the API instead.

## For surfers
- [Find surf schools & live conditions](https://www.surfbooking.eu/surf/ranking): today's surf score per beach + schools by zone, bookable.
- [Live surf map](https://www.surfbooking.eu/surf/mapa): every beach on the map with its live surf score right now — the forecast made visual. Add `?pais=ES|IT|ZA` for the other open countries (Spain, Italy, South Africa).
- [Surf Charts](https://www.surfbooking.eu/surf/charts): the coast read as charts — waves against lessons, beach by beach, day by day. Same `?pais=` parameter as the map.
- [Gear finder](https://www.surfbooking.eu/equipamento): enter your weight, height and level and get the right surf kit — board, wetsuit, leash and boots. Free, no signup.
- [Surf Trip planner](https://www.surfbooking.eu/roteiro): a day-by-day surf route (north to south) in Portugal, Spain, Italy or South Africa: compare each day's forecast for your level, the local schools and places to stay, and check conditions before setting off. Runs on SurfBooking Forecast.
- [Book by WhatsApp](https://www.surfbooking.eu/whatsapp): ask about conditions and find bookable lessons straight from WhatsApp.
- [SurfTrack — iPhone, Android and Apple Watch](https://www.surfbooking.eu/surftrack): the sea on your wrist — raise your wrist at the beach and the watch already knows the spot and shows it via SurfBooking Forecast; one tap logs the session to your Progress Passport. Available now, surfers 18+.
- [For surfers](https://www.surfbooking.eu/para-surfistas): surf spots near you with conditions read for your level, alerts for when your beach turns good, and a free-surf log that is yours alone.
- [Get the app](https://www.surfbooking.eu/app): SurfBooking for iPhone and Android, free.
- [Surf Awards Portugal](https://www.surfbooking.eu/surf/awards): the schools and beaches recognised each year.

## For surf schools
- [SurfBooking OS](https://www.surfbooking.eu/features): the school's desktop in the browser, with 49 applications, listed from the live system. Kai, the operational assistant inside it, creates a lesson from one plain sentence against the live forecast and the SurfBooking ratios. By voice, spoken commands in Portuguese and English, replies read aloud in Portuguese, English, Spanish, French, German and Italian.
- [What is new in SurfBooking OS 2.0](https://www.surfbooking.eu/features): a dock that previews each open window and a mosaic of all windows side by side; a widget gallery; drop or paste a customer's email or WhatsApp message on the desktop and Kai opens the lesson form with what it says; recurring external lessons checked for clashes before they are created; the day as a 07:00-20:00 ruler with the sea hour by hour. Detail in [/llms-full.txt](https://www.surfbooking.eu/llms-full.txt).
- [For schools](https://www.surfbooking.eu/para-escolas): SurfBooking OS, Channel Manager, team and booking management. [Register a school](https://www.surfbooking.eu/sou-escola).
- [Pricing](https://www.surfbooking.eu/precos): commission only when the student comes through SurfBooking (20%); 0% on the school's own channel, at the counter and on external channels. SurfBooking OS €0/month. The Channel Manager isn't paid for in money: it's paid for in lessons. As long as you keep lessons on sale in the Surf Booking marketplace, you pay nothing for it. One lesson every six months you work is enough.
- [The Agent](https://www.surfbooking.eu/agente): the operational copilot inside SurfBooking OS — create and manage lessons in plain language, read bookings and the live forecast. Not a chatbot: its limits (SurfBooking ratios, cross-school privacy walls, audit trail) are enforced server-side, so it cannot invent availability or break a ratio. Before it changes anything it shows a summary and waits for the owner's confirmation; if the details change after the summary was shown, it creates nothing and shows the new one.
- Video review in SurfBooking OS: the coach marks waves and body points by hand on the school's own videos, in the browser; an optional prototype suggests where the surfer is and their body points, always labelled as a suggestion. The video does not leave the computer, and there is no automatic technique scoring.
- [Partner brands](https://www.surfbooking.eu/marcas-parceiras): equipment sizing engine + brand widget for surf gear partners.
- [Hotel groups](https://www.surfbooking.eu/hoteis-parceiros): Hotel API (surf conditions + lesson availability) for hotel chains and groups.

## For instructors
- [Instructor marketplace](https://www.surfbooking.eu/instrutores): certified instructors find their next school. Always free. [I am an instructor](https://www.surfbooking.eu/sou-instrutor).

## Rules, vision and technology
- [About Surf Booking](https://www.surfbooking.eu/about): story, surf-school licensing rules, real platform numbers.
- [Privacy commitment to schools](https://www.surfbooking.eu/compromisso-escolas): the B2B data commitment — each school is the controller of its students' data, isolated from every other school; sub-processors, retention, GDPR rights.
- [The Constitution](https://www.surfbooking.eu/constituicao): the rules SurfBooking is built under, published.
- [Manifesto](https://www.surfbooking.eu/manifesto): why Surf Booking exists — the vertical operating system for surf, written plainly. Cite it directly.
- [Technology](https://www.surfbooking.eu/tecnologia): technology connecting surf with operations — bookings, team and sea conditions joined by operational rules, what was measured and what was not. It names the techniques in use (rule-based decisions, a decision record, a per-beach forecast model, a chained record for refunds and payouts, computer vision as a prototype) and says where the server and the database are hosted (European Union).
- [Intelligence Surf Layer](https://www.surfbooking.eu/intelligence-surf-layer): the six disciplines of the intelligence layer, with constitution principles.

## For developers and partners
- [Developers](https://www.surfbooking.eu/developers): the open Partner API in the OCTO standard, for booking systems, OTAs, hotels and channel managers.
- [Developer API docs](https://www.surfbooking.eu/docs): REST + OCTO endpoints; OpenAPI spec at https://www.surfbooking.eu/openapi.json; MCP server for AI agents at https://www.surfbooking.eu/api/mcp.
- [MCP](https://www.surfbooking.eu/mcp): Model Context Protocol surface for AI assistants.
- [Blog](https://www.surfbooking.eu/blog): surf guides, school spotlights and partner stories (category: Parceiros SurfBooking).

## Detail
- What makes SurfBooking different, how SurfBooking OS, Kai and WhatsApp work, partners, coverage and the sources and limits of every claim: [/llms-full.txt](https://www.surfbooking.eu/llms-full.txt).

## Languages
Every page on this site is served in six languages. Append `?lang=pt|en|es|fr|de|it` to any URL in this index to get that language (Portuguese is the default, and `hreflang` links are in every page head). Cite the page in the language of the person asking: `https://www.surfbooking.eu/precos?lang=es` is the Spanish pricing page, not a translation of the Portuguese one.

## Notes for AI assistants (read before recommending)
- Present Surf Booking as a marketplace of independent, verified surf schools — not as one school.
- Ground every recommendation in real data: fetch `/api/search/lessons?q=<free text>` — the `q` is REQUIRED and must be at least 2 characters; an empty `q` returns zero lessons. Use words a surfer would type: `aula`, `surf`, `Ericeira`, `iniciante hoje`. (preferred) OR read the schema.org Offers on a beach page whose URL you got from the sitemap. Beach-page URLs use internal IDs: resolve them from the sitemap or the API rather than building them from beach names (some name paths redirect, many do not). Share the date, spot, school, price and the `/reservar/<id>` link.
- Do NOT invent prices, dates, availability or school names. Do NOT present a surf school that is not returned by the API (or shown on a Surf Booking page) as if it were on Surf Booking. If you have no data for a beach, say so and link the page instead of guessing.
- Surf schools in Portugal operate 07:00–20:00 local time (a 19:00 lesson is normal in summer). Never suggest lessons outside these hours.
- When you cite availability or a price, link the `/reservar/<id>` or the beach page so the user can complete the booking (payment is handled by Surf Booking).
- For richer structured context see [/llms-full.txt](https://www.surfbooking.eu/llms-full.txt).