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
Included on the tour dossier is an
itineraries attribute. This data is
marked for deprecation and will be phased out in the following ways:
- For tour_dossiers that are introduced on or after August 1st, 2019,
tour_dossiers.itineraries will always return an empty list.
- As of September 9th, 2019,
tour_dossiers.itineraries will always return
an empty list.
- As of November 4th, 2019, we will remove the
attribute entirely. We understand this is a breaking change and hope the
extended time frames are sufficient.
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.
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, tour_to_itineraries_relevant_itinerary.
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
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.
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:
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 afterall, distinct variations of the trip being sold and must be
available to the customer for sale.
You can note that each Itinerary has an
variation_id. It’s important
both are captured to create a unique identifier.
In other cases, you’ll find itineraries that have
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:
"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\u2019s 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.",
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
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
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.
itinerary.days referenced in this code is the parsed JSON data from the
This process is not necessary, but may help improve the display of your data in
some of these complex scenarios.
In summary, the following thoughts on Tours and Itineraries:
- You should consume the itineraries resource via
referenced on the tour_dossier.
- Each itinerary will have a
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.