Advanced Guide Integration

Welcome to the advanced guide on integrating Swiss Activities using the Leisure Link API. This document expands on the use of our API, focusing on the details of activity endpoints, including availability and dates, to empower your e-commerce platform with dynamic and detailed content.

Best Practices for E-commerce Integration

Implement Robust Data Handling

Define how to manage and utilize the extensive data from the API, focusing on privacy and efficiency.

Enhance Search Functionality

Use the API's robust capabilities to enhance user experience and facilitate the easy discovery of activities, ensuring features like dynamic content adaptation to user preferences and real-time availability updates.

Dynamic Content Creation

Leverage the API to create dynamic and responsive content based on real-time data, such as availability and pricing, which is crucial for maintaining accuracy and enhancing user trust in your platform.

Language Support and Localization

Our API supports a wide range of languages, ensuring you can cater to a global audience seamlessly. These languages include but are not limited to English, German, French, Italian, Spanish, Japanese, and Chinese.

Additional Services and Support

• Proprietary Search Engine: For a fee, integrate our advanced search engine into your system for enhanced search capabilities.
• Consultation Services: Gain expert insights through our consultation services to optimize your API integration. Note that development services for websites or backend systems are not provided.

Important Considerations

• Content Adaptation: Utilize tools like OpenAI to adapt the content's tone and style to fit your platform seamlessly. We believe that in current development content is getting more a commodity. All our content is carefully research and clarified with our partners. You don't need to make the research and instead you can reuse our content and with help of AI, you can rewrite it.
• Image Customization: Refer to the documentation of our CDN provider, IMGIX, for guidelines on how to modify images (style, size, crop, etc.), particularly for optimizing mobile applications. Based on your needs you can change the size, format, crop etc. for your purpose.
• SEO Practices: Ensure to use proper sources or canonical tags to credit Swiss Activities as the content source to avoid penalties in organic traffic (dublicate content). Search Engine has no problem for reusing content as long as they understand the source.

Activities Endpoint (/activities)

Endpoint: /activities

Description: This endpoint serves as the core of the API, returning a curated list of activities based on specified filters such as type, location, point of interest, and attributes. This functionality is essential for platforms aiming to offer tailored travel and adventure experiences to users.

Purpose:

• Customization: Allows users to find activities that match their specific interests and preferences.
• Integration: Seamlessly integrates with e-commerce platforms to enhance user experience by providing relevant activity suggestions.
• Flexibility: Supports various queries, making it versatile for different types of users and use cases.

Example Response:

{
  "activities": [
    {
      "id": 7,
      "name": "Ballonfahrt Schweiz 2 Stunden Region nach Auswahl",
      "description": "Offering unique aerial views of Switzerland, this balloon ride is a must-try adventure. Available locations vary based on weather, including Zurich and Lucerne...",
      "onRequest": true,
      "galleryUrls": [
        "https://contentapi-swissactivities.imgix.net/contentapi.swissactivities/Heissluftballon_Westschweiz_3b93a07ae6.jpg",
        ...
      ],
      "meetingPoint": {
        "name": "Individually agreed meeting point",
        "address": "Luzern, Zentralstrasse 1, 6003 Luzern, Schweiz"
      },
      "included": ["2-hour flight", "Certified equipment", "Refreshments"],
      "highlights": ["Private balloon flight", "Choose your region", "Apéro included"],
      "startingPrice": {"amount": "1500.00", "currency": "CHF"}
    },
    // Additional activities...
  ],
  "paging": {
    "totalCount": 949,
    "offset": 5,
    "limit": 5
  }
}

Pagination: This feature is critical for handling large datasets efficiently. It allows platforms to load data incrementally and manage system resources better, improving the user experience by ensuring that the app remains responsive and fast.

Practical Use:

• Travel Agencies: Can integrate these activities into their booking systems to provide customers with various options tailored to their preferences.
• Personalized Recommendations: Platforms can use customer data to suggest activities that align with past preferences and interests.
• Dynamic Content: Helps keep the content fresh and engaging by updating it based on availability and user interests.

This endpoint's robust functionality and flexibility make it indispensable for creating a dynamic and user-centered travel or adventure booking experience.

Activities by Attribute (/activities/attribute)

Endpoint: /activities/attribute

Description: Retrieves a list of attributes that can be used to filter activities based on specific interests or themes.

Example Response:

{
  "attributes": [
    {"id": "21", "value": "Ticket"},
    {"id": "22", "value": "Stadtführung & Stadtrundfahrt"},
    {"id": "24", "value": "Tour"},
    {"id": "95", "value": "Sommeraktivität"},
    {"id": "97", "value": "Ganzes Jahr"}
  ],
  "paging": {
    "totalCount": 91,
    "offset": 5,
    "limit": 5
  }
}

Activities by Location (/activities/location)

Endpoint: /activities/location

Description: Fetches activities based on their geographical locations, providing insights into specific regional offerings.

Example Response:

{
  "locations": [
    {
      "id": "194",
      "title": "Region Aargau",
      "description": "The region encompasses rural areas and urban centers, highlighting the 'water castle' where major rivers meet...",
      "slug": "region-aargau",
      "teasureImage": {
        "alternativeText": "Bremgarten Aargau",
        "url": "https://contentapi-swissactivities.imgix.net/.../river_5581185_7ccbbc22e5.jpg"
      },
      "numberOfActivities": 0
    },
    // Additional locations...
  ],
  "paging": {
    "totalCount": 283,
    "offset": 5,
    "limit": 5
  }
}

Activities by Type (/activities/type)

Endpoint: /activities/type

Description: This endpoint lists the types of activities available, such as adventure sports, cultural tours, etc., aiding in targeted content delivery.

Example Response:

{
  "types": [
    {
      "id": "22",
      "title": "Fallschirmspringen",
      "description": "Offers skydiving experiences across various hotspots in Switzerland, accessible to beginners and enthusiasts alike...",
      "slug": "fallschirmspringen"
    },
    // Additional types...
  ],
  "paging": {
    "totalCount": 105,
    "offset": 5,
    "limit": 5
  }
}

Single Activity Detail (/activities/{activityId})

For detailed information on a specific activity, the /activity/{id} endpoint provides everything from metadata to rich descriptive content:

• ID & Basic Info: Each activity has a unique identifier.
• On Request: Indicates if the activity requires confirmation.
• Gallery URLs: A list of high-resolution images that visually represent the activity.
• Details: Includes deep dives into descriptions, accessibility, highlights, and practical tips.

Endpoint: /activities/{activityId}

Description: Provides detailed information about a specific activity, including descriptions, images, and practical information such as meeting points and included services.

Example Response:

{
  "id": 398,
  "onRequest": false,
  "galleryUrls": [...],
  "detail": {
    "name": "Ticket Standseilbahn Harder Kulm ab Interlaken Ost",
    "description": "Describes the short but steep ride from Interlaken to Harder Kulm, highlighting views and amenities...",
    "meetingPoint": {
      "id": "46282",
      "name": "Harderbahn, Brienzstrasse 1, 3800 Interlaken",
      "latitude": "46.691014",
      "longitude": "7.865387000000001",
      "address": "Harderbahn, 3800 Interlaken, Schweiz"
    },
    "included": ["Bahnfahrt mit Harderkulmbahn"],
    "highlights": ["Enjoy the modern funicular ride to Interlaken's local mountain, visit the viewing platform at 1,322 meters above sea level..."]
  },
  "infoTeaser": "Take a 10-minute funicular ride from Interlaken Ost to Harder Kulm, offering stunning views and a panoramic restaurant...",
  "startingPrice": {
    "amount": "9.50",
    "currency": "CHF"
  }
}

Activtiy Availabilities and Dates

Understanding availability and dynamic pricing is critical for accurate bookings. You also can build your own calendar.

• Endpoint: /activities/{activityId}/dates
• Functionality: Fetches all available dates along with capacity and dynamic pricing.

Example of dynamic date and price retrieval:

{
  "availableDates": {
    "2024-05-01": {"price": null, "capacity": "none"},
    "2024-05-02": {"price": null, "capacity": "none"},
    "2024-05-04": {"price": "CHF 9.50", "capacity": "unlimited"},
    "2024-05-05": {"price": "CHF 9.50", "capacity": "unlimited"},
    // Additional dates...
  }
}

Activity Availabilities (/activities/{activityId}/availabilities)

The /availabilities endpoint provides comprehensive details about bookable offers:

• Bookable Offers: Different classes or types of bookings available (e.g., first class, round trip).
• Ticket Categories: Specifies categories such as adult, child, senior, along with pricing and restrictions.
• Availability Slots: Exact times and dates for when the activity can be booked.
• Personalized Fields: Automatically generates necessary customer queries based on the selected activity, reducing manual input and errors.

Example Response:

{
  "offerId": 5556,
  "contentApiOfferId": 3869,
  "offerLabel": "Ticket Harder Kulm einfach",
  "ticketCategories": [
    {
      "ticketCategoryId": 37054,
      "minAge": 16,
      "price": {
        "amount": "19.00",
        "currency": "CHF",
        "formatted": "CHF 19"
      },
      "audience": "adults",
      "discountType": null,
      "label": {
        "formatted": "Erwachsene (ab 16 Jahre)",
        "audience": "Erwachsene",
        "ageRestriction": "ab 16 Jahre"
      }
    },
    // Additional categories...
  ],
  "availabilities": [
    {
      "availabilityId": "ava_398_94151_1714773600_1714859999",
      "ticketCategoryIds": [37054, 37055, 37056, 37057, 37058],
      "isAllDay": true,
      "startsAt": "2024-05-04T00:00:00+02:00",
      "endsAt": "2024-05-04T23:59:59+02:00",
      "cutoff": "2024-05-04T23:59:59+02:00",
      "capacity": null,
      "cancellableUntil": "2024-05-03T00:00:00+02:00"
    },
    // Additional availabilities...
  ]
}

For further assistance or to discuss potential enhancements to the API, please contact [email protected].