Using Itineraries For A Tour
In this tutorial, we’ll go over our itineraries resource, and how to
fetch the relevant
Historically, Tour Dossiers have been the go-to resource for all information
about a tour, and many integrations still use the itineraries object on
this resource to easily get a summary of itinerary data.
For example, the following tour_dossier has data which looks like this
"body": "Arrive at any time.",
"label": "Day 1 Shanghai"
"body": "Enjoy free time or join the CEO for a walk through the Bund, Old Shanghai, People's Park, and more. Board a bullet train to Wuyishan in the Fujian province.",
"label": "Day 2 Shanghai/Wuyishan"
This itinerary data is very simple, and unstructured. It’ll provide you the most
basic means of fetching the tour information and is not very flexible.
As Of July 2015, we released the itineraries object. This is a more structured
implementation of our 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.
Effectively, this resource is a very powerful way to display G Adventures tour data.
We do highly recommend it for an integration to be successful in its display of G Adventures content.
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.
Generally, most tours will indeed 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, if you plan to show all Itinerary options to the user, you can use
a few key pieces of data to achieve proper segmentation in your database.
You’ll notice that we supply a
variation_id. This, coupled with the
the Itinerary will provide you with a unique combination. Then, you’ll want to
valid_during_ranges attribute. If you consume all Itineraries,
then you’ll want to display the Itinerary appropriate for today, based on
valid_during_ranges. If a date in this list is
null, it means
that it has no end point and is the Itinerary valid for the rest of the tours
The key to success in consuming these is to store them locally, and organize
the data using these key attributes. All itineraries do reference a parent
tour_dossier, so you’ll be able to group them that way as well.
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.