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

GET /tour_dossiers/23308

"itineraries": [
    {
        "type": "SUMMARY",
        "duration": 10,
        "days": [
            {
                "id": "13946",
                "body": "Arrive at any time.",
                "label": "Day 1 Shanghai"
            },
            {
                "id": "13947",
                "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.

"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 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 id of the Itinerary will provide you with a unique combination. Then, you’ll want to inspect the 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 life cycle.

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:

GET /itineraries/1960/2134

"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\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.",
        "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.