zdl-datalake

Events Admin Find Candidates

Find existing events in the data lake that might be duplicates of a candidate event. Uses fuzzy matching on name, date proximity, and geographic proximity. Returns a scored list of candidate matches with matchScore and dateDiffDays. USE THIS BEFORE CREATING: always call this first to avoid inserting duplicate events. DECISION THRESHOLDS: - matchScore >= 0.80 AND dateDiffDays == 0 → same event → call events_admin_update - matchScore >= 0.85 AND dateDiffDays <= 1 → same event (minor date diff)

Events Admin Get

Retrieve a single tourism event by its system-generated ID (systemId). Returns full event details including venue, dates, source, demandPressure, and overlapCluster. Use this after events_search to get complete details of a specific event.

Destination Get Report Options

Returns all available filter values and aggregation fields for destination demand and reservation reports. Call this when you need the complete list of valid values for filters, aggregation fields, or source channels. No parameters required — returns everything in a single response with domain annotations.

Events Admin Create

Create a new tourism event in the Zucchetti Travel Data Lake. Returns the system-generated ID (systemId) to be stored for future updates. IMPORTANT: Call events_admin_find_candidates first to avoid duplicates. REQUIRED FIELDS: name, category, date_start, date_end, venue_country_code, source_system. For scope=Venue (default): also venue_city, venue_lat, venue_lon are required. For scope=City: venue_city is required, coordinates optional. For scope=National: only venue_country_code is required.

Events Admin Upsert Autodedup

Automatically create or update a tourism event applying the full deduplication workflow in a single call. Reduces token usage by orchestrating the lookup → find-candidates → create/update flow internally. DEDUPLICATION WORKFLOW: 1. If external_id is provided: try GET /events/by-source/{source_system}/{external_id} - Found → update the existing event - Not found → continue to step 2 2. Call find-candidates to detect potential duplicates - No candidates → create new event - matchScore

Destination Demands Run Report

Run a custom analytics report on tourism DEMAND data — i.e. accommodation searches performed by travellers on booking engines. Demand data captures WHAT travellers are looking for (destination, dates, rooms, guests) and WHEN they searched, which typically happens weeks or months before the actual stay. KEY CONCEPTS: - SEARCH PERIOD (search_period_from/to): when the searches were performed. Optional — defaults to last 91 days up to today if omitted. This is the observation window for the report.

Events Admin Get By Source

Retrieve a single tourism event by its source system and external ID. Use this for fast lookup when you know the externalId assigned by your source system (e.g., Ticketmaster ID). Returns the systemId needed to perform updates. This is faster and more precise than events_admin_find_candidates when the externalId is stable.

Events Search

Search tourism events in the Zucchetti Travel Data Lake. Returns a paginated list of events matching the specified filters. Provide at least one filter to narrow results. GEOGRAPHIC FILTER: provide venue_lat, venue_lon, and radius_km together to search events near a location. All three parameters are required if any one is provided. DATE FILTER: use date_start_from and/or date_start_to to filter by event start date. FULL-TEXT SEARCH: use search_name, search_description, search_location for fu

Events Admin Update

Fully replace an existing tourism event by its systemId (PUT — full replace, not partial update). ALL fields must be provided, not just the changed ones. If the systemId does not exist, the API will create a new event and return a new systemId (201). DATES: YYYY-MM-DD format only. IMPORTANT: PUT is a full replacement. Always send all fields to avoid accidental data loss.

Destination Reservations Run Report

Run a custom analytics report on accommodation RESERVATION data (actual confirmed bookings). Use this to analyze booking volumes, stay patterns, guest composition, and advance booking behavior. KEY CONCEPTS: - BOOKING PERIOD (booking_period_from/to): when the reservations were made. Optional — defaults to last 730 days (2 years) up to today if omitted. This is the observation window for the report. - STAY PERIOD (stay_date_from/to): the actual stay dates of the reservations (check-in range). Re