Things-To-Do Start Guide

The following tutorial describes common integration use cases for partners in the Things-to-do space. This applies for any partner that sells tickets to museums, attractions, tours, activities and events.

Integration

Follow the high level integration process outlined in the end-to-end integration guide, implementing the Order-based methods. Also, all things-to-do partners will integrate with payments, so please reference the enabling payments guide. When connecting tours, activities, and attractions products to locations / POIs, follow the policies in Things-To-Do Vertical Policies for Tours, Activities and Attractions

Key Differences

  • Feeds: Generate merchants, services, and availability feeds including ticket, service locations, and payment information
    • For help with the availability feed, refer to How to structure availability with ticket types
    • For tours, or services that visit multiple locations, refer to Setting Multi-location Services for help setting service locations.
    • For attraction admission tickets, the venue should be set as the "Merchant". (e.g. Admission ticket to the Louvre Museum). The venue must have a business relationship with you.
  • Booking Server: Implement the Order-based Implementation of the booking server with the following methods:
    • HealthCheck
    • CheckOrderFulfillability
    • CreateOrder
    • ListOrders
  • Real-time updates: Implement the two mandatory RTU APIs

Common Use Cases

Below are integration details for the most common use cases.

Specifying entrance tickets for attractions

By default, an availability slot represents the specific time that a user must arrive at the merchant. For admission and entrance tickets, however, users can go to the venue at any time during a time range (for example, tickets to Disney World). In this case, users can order tickets even after the start time has passed.

Services Feed:

  • Under SchedulingRules, set admission_policy to TIME_FLEXIBLE
  • Under SchedulingRules, set min_booking_buffer_before_end_time as a positive value to allow bookings to be made after the slot begin_sec

Availability Feed:

  • Set time slots to be the venue’s open business hours. If there are no opening hours for the venue, set the time range to be up to 24 hours (for example, 12am to 12am, or 12am to 11:59pm), but make sure that the start and end time works correctly with your booking server, as these times are used to identify the availability slot during booking.

Defining multi-day passes or tickets

Services Feed:

  • Under SchedulingRules, set admission_policy to TIME_FLEXIBLE
  • Under SchedulingRules, set min_booking_buffer_before_end_time as a positive value to enable booking after slot start time
  • Ensure the ticket’s validity time is made clear by either of the following:
    • Create a different ticket type for each pass (1-day vs. 3-day pass) of a product
    • Define detailed service names and descriptions if the duration applies to all tickets of the service

Availability Feed:

  • Include begin_sec, end_sec, and duration per day even if the ticket spans several days, because these are required fields. Currently, duration cannot be longer than 24 hours. However, this doesn't mean that the duration that the ticket is valid for needs to be within 24 hours. The slot duration will not be shown to users as long as the service scheduling rules are specified correctly.
    • Pick an end_sec that is start_sec < end_sec <= start_sec + 24x3600 (preferably after the venue closing time so that tickets can still be booked after the start time has passed when min_booking_buffer_before_end_time is set), and is consistent with how your booking server validates availability for CheckOrderFulfillability and CreateOrder requests.

Specifying tickets or activities with an unknown end time

Services Feed:

  • Under SchedulingRules, set admission_policy to TIME_FLEXIBLE (if entry and exit time are flexible) or TIMED_ENTRY_WITH_FLEXIBLE_DURATION (if entry time is set but exit time is flexible)

Availability Feed:

  • Include the begin_sec, end_sec, and duration even if the end time is unknown because they are required field. However, the slot duration will not be shown to the users as long as the scheduling rules are configured properly.
    • Pick an end_sec that is start_sec < end_sec < start_sec + 24x3600 and is consistent with how your booking server validates availability for CheckOrderFulfillability and CreateOrder request

Representing dynamic prices

Dynamic pricing is supported for certain use cases where ticket prices can differ based on time slots, for example, weekend versus weekday prices. This model works best if ticket dates and prices change only occasionally. If prices can fluctuate drastically for your products within 30 days, please reach out to your Google contact for further discussion.

Services Feed:

  • Define slot level ticket types by pricing, for example adult_weekday, and adult_weekend tickets.
    • The two ticket types can have the same description (e.g."adult") but different prices

Availability Feed:

  • For each availability slot, set ticket_type_id to the subset of ticket types that are eligible for this slot defined in the services feed

Real-time updates:

  • When a ticket price for a product changes, update the price through a real-time update API call, or update it in the next daily feed

Defining service descriptions for tours, activities, and attraction tickets

  • Use structured service fields where possible, using ToursAndActivitiesContent message, to keep flexibility for user-friendly rendering on different surfaces. Structured fields allow listing the following Things-To-Do specific details:

    • Highlights: The most prominent features of the service.
    • Includes: What is included with the purchase.
    • Excludes: What additional items would be required to make full use of this service or that a user might mistake for being included.
    • Must knows: Any information that could limit who is eligible to make this purchase. Examples include: "Child tickets must be purchased with an adult ticket".
  • For service descriptions, use HTML. Refer to the specifications to see which tags are supported.

  • Avoid duplicating information already present in the structured service fields in the description field. Instead, make sure the following details are covered:

    1. Description
      • A clear description of the service you will be providing.
    2. Departure Point [Tours Only]
      • A user should be clear on where they will be expected to arrive to use their ticket.
    3. Itinerary
      • Where applicable, locations visited during a tour and the schedule.

Setting cancellation policy

The CancellationPolicy field is a mandatory field that should be used to define the cancellation policy for the service. The structured field will be rendered in surface-specific manner (icons, text, filters) and localized for display.

Cancellation policy should be declared with one or more refund_condition values. Each refund condition includes the duration before the service start time when the cancellation is possible, and the allowed refund percentage.

For example, the cancellation policy of:

  • Full refund 7 days before service start time
  • 50% refund 48 hours before service start time
  • Not refundable less than 24 hours before service start time

should be set up as following:

  cancellation_policy {
    refund_condition {
      min_duration_before_start_time: 604800 # 7 days
      refund_percent: 100
    }
    refund_condition {
      min_duration_before_start_time: 172800 # 48 hours
      refund_percent: 50
    }
    refund_condition {
      min_duration_before_start_time: 86400 # 24 hours
      refund_percent: 0
    }
  }

Using custom intake forms

Custom intake forms allow you to collect essential information from users at the time of reservation. Examples of essential information are the weight of a person for a skydiving service and the customer’s pickup location for a taxi tour.

In order to ensure the checkout experience is as frictionless as possible for users, custom intake forms should not be used for non-essential questions such as "how did you hear about us?" (even if the field is not marked as required). Too many questions will reduce the likelihood of users completeing the checkout flow and booking the service.

There are two possible intake forms that can be used:

  • Per ticket form: The fields in this form will be repeated for each ticket that the user purchases. You should use this if you need to tie information about the user to the individual ticket.
  • General form: The fields in this form are shown once per order regardless of how many tickets are purchased. You should use this to collect party/order level information.

The following question types are available, and each question can be marked as required or optional:

  • Short answer
  • Paragraph
  • Multiple choice
  • Checkboxes
  • Dropdown
  • Boolean (yes or no)
  • Location search (e.g. for hotel pick-up)

Custom intake forms are defined at the service level feed and the user responses will be passed to your booking server inside of the order specification.