Using Itineraries For A Tour

In this tutorial, we’ll go over our itineraries resource, and how to fetch the relevant itineraries for a tour dossier.

Historically, the tour dossier contained an assortment of itinerary details for a tour. As the G Adventures API has evolved to provide more structured data, we have evolved this offering.

Today, we recommend one treats the tour dossier as the lead to access and discover itinerary data. Each tour dossier will contain a list of structured_itineraries, which provide references to the itineraries of this resource. You’ll want to paginate over tour_dossiers as that lead, then discover Itinerary content and beyond through that iteration.

Deprecation of tour_dossiers.itineraries

As of November 4th 2019, an itineraries attribute was removed from the Tour Dossier resource. This was communicated over a phased 6-month deprecation.

The alternative? The more robust itineraries object referenced as structured_itineraries within the tour_dossiers resource. This is a more structured implementation of our previous tour details, with some major benefits:

  • Every day is structured, providing you better control of how to display the data.

  • Each day has referenced components, detailing the included activities that occur each day.

  • Each activity and data entry that is applicable, has geo-coordinates supplied via the places object.

  • It is actively managed and is sourced from our active product management systems.

Effectively, this resource is a powerful and flexible way to display G Adventures tour data. It is also the most accurate, ensuring a better customer experience.

Once the timeline above has passed, we will not revert back, so please update.

Migration Mapping

Please reference the below table to help map the deprecated tour_dossiers.itineraries to their new format. This assumes you have chosen the appropriate Itinerary for the Tour Dossier, which you can read more about below, Getting The Relevant Itinerary.

tour_dossiers resource

itineraries resource

itineraries[].days[]

.days[]

itineraries[].days[].body

.days[].summary

.itineraries[].days[].label

.days[].label

Additionally, the id presented in each day object on both resources match up

Itineraries contain plenty of additional information that you can pick and choose as you wish, and the above will help you map the existing integration to the new scheme, allowing you to expand in the future

Getting The Relevant Itinerary

On the tour dossier object, we display an attribute named structured_itineraries. This is a list of Itineraries applicable to this tour. A few reasons why a tour may have multiple itineraries:

  • A tour may slightly change its itinerary depending on the season

  • A tour may vary for a small length of time, perhaps one week. This is common when the tour goes through an area in which a festival may be occuring at the time.

  • For many trips visiting Machu Picchu in Peru, there is an included hike. We offer passengers to take the Inca Trail, Lares Trek, or stay in Cusco. These are all different itineraries.

Let’s look at what the nested attribute looks like.

"structured_itineraries": [
{
    "id": "985",
    "variation_id": "964",
    "href": "https://developers.gadventures.com/playground/itineraries/985/964",
    "valid_during_ranges": [
        {
            "start_date": "2015-01-01",
            "end_date": null
        }
    ]
}
]

Generally, most tours will have one itinerary, but you want to build your system to capture more, if they exist. For your convenience, the first itinerary within the structured_itineraries list is the “best choice”. Generally, this is the itinerary that is most relevant to the passenger at time of consumption of the itinerary data. If your initial integration does not plan to offer options like the Peru Inca Trail / Lares Trek options, then you should be able to get by simply using the “best guess” itinerary from this list for display.

Otherwise, it’s important to show multiple Itinerary options. Take this example of the Inca trail from gadventures.com:

../_images/itineraries-inca-multi.png

Here, the list of structured_itineraries is more than one, and the dates overlap. This is the most complex form of multiple itineraries, as you’d be expected to provide a similar Itinerary switcher for your customers.

Each Itinerary in this situation will have a name that contains data, which you can display in a tabbed interface similar to the above. You will want to treat each itinerary, even ones with overlapping dates as unique itineraries. They are after all, distinct variations of the trip being sold and must be available to the customer for sale.

You can note that each Itinerary has an id and variation_id. It’s important both are captured to create a unique identifier.

In other cases, you’ll find itineraries that have valid_during_ranges which do not overlap like the Inca Trail. These are usually tours which have seasonal adjustments.

For example, a sailing trip to Greece will look different in their winter and summer, so we provide multiple itineraries to ensure you can inform customers based on the departures they chose.

Finally, each Departures references its relevant Itinerary. Thus, when a customer is viewing a particular Itinerary, you can ensure that only departures relevant to that Itinerary are displayed. How you approach this flow is customizable to your style and customer.

Understanding Itinerary Days

The Itinerary object looks complex, but it’s simply a lot of data. Once you begin parsing it, you’ll find how useful the information is! One interesting scenario within the Itinerary is how we manage days.

On many trips, there are scenarios where across two or more days, the same activities and daily itinerary apply. Think of a G Adventures tour where you have three days of “Free Time”. This is common for many trips within South America as an ending point to a busy itinerary.

Let’s look at how a days object looks like. Here’s a snippet:

{
  "days": [
    {
      "id": "15040",
      "day": 1,
      "summary": "Arrive at any time and transfer to the hotel. ",
      "description": "A G Adventures representative will greet everyone at the hotel and brief the group on the various aspects of the tour. ",
      "instructions": "If you are not able to attend the welcome meeting, a representative will leave all important information at the hotel’s reception indicating what time to be ready on Day 2 of the trip. If there is any confusion on arrival, please do not hesitate to call the contact number listed in this dossier.",
      "start_location": {
        "id": "2062797",
        "href": "https://developers.gadventures.com/playground/places/2062797",
        "name": "Quito"
      },
      "end_location": {
        "id": "2062797",
        "href": "https://developers.gadventures.com/playground/places/2062797",
        "name": "Quito"
      },
      "meals": [],
      "components": [
        "..."
      ],
      "optional_activities": [
        "..."
      ]
    }
  ]
}

Each day object has a summary, description, start/end location, meals, and a list of component objects, which in very fine detail describe the days activities. As a consumer of this data, it is up to you to decide what you want, but at the least, we recommend the summary and description. Components provide very fine grain data about the day, and are not necessary to sell the trip (but will provide the customer with more data!)

One thing to note, is that the day has an id. You must identify this specifically for the purpose of the aforementioned scenario where a “Free Time” type of day may extend for two or more days.

When looping through the days, you can inspect the id, and if the id of the day next in the loop matches the previous one, this is the same data, simply extended for another day. The reason we’ve done this is to be very granular, but to allow each day to have a specific day attribute.

You can be smart about displaying this data by merging these days when the id matches. Here you can see a Python snippet of how this merger occurs on the G Adventures website.

../_images/day-merging.png

The itinerary.days referenced in this code is the parsed JSON data from the itineraries resource days attribute.

This process is not necessary, but may help improve the display of your data in some of these complex scenarios.

Summary

In summary, the following thoughts on Tours and Itineraries:

  • You should consume the itineraries resource via structured_itineraries, referenced on the tour dossier.

  • Each itinerary will have a variation_id and valid_during_ranges attribute. We show the most appropriate itinerary in the structured_itineraries at time of consumption as means of convenience.

  • Once you have the appropriate itineraries resource, simply consuming the days will provide you the most important data you need.

  • Documentation for the Itinerary object is available within our itineraries documentation.