Zarvo

Use this when a group wants bookable court options near a UK location on one date or across a bounded date range. Searches configured providers, normalizes known whole-court and per-player prices, adds catalogue venue IDs and coordinates, and returns at most the requested limit across all dates. Providers such as MATCHi may return a null anonymous price; those slots remain visible under a price ceiling with price_details.basis unknown and must not be presented as budget matches. Travel time is a straight-line heuristic with a 15% soft-filter tolerance near max_travel_minutes, not live routing. number_of_players affects per-player price only; use singles_court to require explicit singles support. Do not use for venue-only discovery or public games.

Use this lightweight directory lookup to find clubs by location and facilities or resolve a club description, nearby landmark, or partial club name into candidate club_id, club_name, and provider values. Put only club-name wording in query; add location when an area was supplied. Use court_type for indoor/outdoor/covered courts, racket_rental for racket hire, and facility for a requested amenity. Preserve these filters when refining a search. Do not infer or pass provider from a club or brand-like name: provider is only an explicit booking-platform hint. If that hint conflicts with the directory, name resolution may return the canonical provider instead. It returns Zarvo club metadata, not live court availability. Follow with get_club for full metadata or get_availability for live slots at a selected provider club.

Use this when a player wants an existing public padel game with an open spot. Omit date, time, level, and limit filters unless the user requested them; by default it returns every matching game around the location across the next 14 UK days. Returns anonymous match metadata and the provider join page; it never reveals player identities or joins on the user’s behalf. Do not use for empty-court bookings.

Use this when a player wants scheduled PadelStars activities such as coaching, training, intro sessions, socials, junior sessions, or competitions. Returns live session times, levels, vacancies, prices when published, and the provider booking page. It never joins, books, or pays on the user’s behalf.

Use this after a Zarvo club ID is known and the user wants its address, coordinates, facilities, racket rental, contact information, official website, or social links. This returns directory metadata, not live availability.

Use this when the user has selected a named provider club and wants its available courts on one date or across a bounded date range. Copy provider and club_name exactly from the selected search_clubs result; never infer provider from the club name. Results include Zarvo club IDs when matched and the total limit applies across all dates. number_of_players affects per-player price only; use singles_court to require explicit singles support. Do not use for a broad nearby search; use search_courts instead.

Optional standalone check. get_booking_handoff already revalidates before returning a URL; call this only to confirm availability without proceeding to handoff. It never books, holds inventory, takes payment, or returns checkout.

Use this only when the user explicitly wants to organise one to three selected court options with other people. Rechecks each selected slot, creates an expiring Zarvo plan, and returns separate guest and private organiser links. This changes Zarvo state but does not book a court.

Use this directly after the user chooses a slot. It revalidates the provider slot and returns status unavailable with a reason if the slot was taken, or status available with a provider handoff URL and current price. The user completes login, booking, and payment on the provider site; Zarvo does not reserve inventory or complete checkout.