Introduction

Itineraries¶

An itinerary is a structured representation of all activities, meals, transports, starting and finishing locations for a tour. At the root of the itinerary, you can find information about the start and end of the trip, included meals and budget, packing lists, and images (for display purposes within your application).

Further into the itinerary, it is segmented into each day. For each day, you can find optional activities, meals, a summary, and components. Each component on a day will include a dossier of a specific type. That dossier can describe an activity that passengers will do on that day, or a transport, like an overnight train.

We recommend reading Using Itineraries For A Tour in addition to this document to help you migrate using itineraries instead of tour details.

Note

The accommodation listed on some itinerary days aren’t necessarily the accommodation that is used on every trip with that itinerary. The accommodation components are meant to describe a representative accommodation for that day. In order to know exactly which accommodation is used on a specific trip, you need to look at the accommodation components on the specific departure or departure service that you are interested in.

Because our products change over time, you’ll find each itinerary has a list of variations. The first variation in the list is the currently valid incarnation of the itinerary and the others are past or future variations. Each variation will have at least one range of dates in which it is valid. This date range may be open-ended.

Itinerary Days

Some days in itineraries have identical content and will therefore have the same ID. The day number will be different between these days, but we recommend rolling up the identical days for display purposes, using a combined label such as “Days 2-4”. For example, take the following (simplified) days list:

"days": [
    {
        "id": "123",
        "day": "1",
        "summary": "Arrive at any time",
    },
    {
        "id": "456",
        "day": "2",
        "summary": "Do some vacation things",
    },
    {
        "id": "456",
        "day": "3",
        "summary": "Do some vacation things",
    },
    {
        "id": "789",
        "day": "4",
        "summary": "Depart at any time",
    },
]

An itinerary with a days list that looks like that should display in something like the following format:

Day 1: Arrive at any time
Days 2-3: Do some vacation things
Day 4: Depart at any time

Handling Multiple Itineraries¶

Each tour dossier references one or more Itineraries. A tour dossier will reference multiple itineraries for a variety of reasons, but generally they are to handle seasonality changes for the tour. The itinerary for a tour can adjust per season, or due to a special event (e.g. Carnival in Brazil). From every tour dossier, you are provided the valid_during_ranges parameter which advices the dates that referenced Itinerary is valid for. These should be used and applied when calculating the appropriate Itinerary to show to the customer.

XML Schema:

itineraries.xsd

Fields

Name	Type	Description
id read-only	String
variation_id required	String	The unique identifier of a specific variation of this itinerary
href read-only	Field
name required	String	A name to help disambiguate between itineraries on the same tour
tour_dossier read-only	Reference Object	A reference to the tour dossier resource with which this itinerary is associated (if applicable)
booking_companies	Field	The booking_company that provide this tour.
id read-only	String
href read-only	Field
flags read-only	Multiple Choice	Flags ON_INCA_TRAIL, ON_LARES_TREK and CUZCO_STAY: For itineraries visiting Machu Picchu in Peru, the presence of these flags indicates that the itinerary includes hiking the Inca Trail (ON_INCA_TRAIL), hiking the Lares Trek (ON_LARES_TREK), or a stay in Cusco (CUZCO_STAY). Flag PRIVATE_DEPARTURES_NOT_AVAILABLE: By default, trips are available for use in Private Group Trips with the exception of some trips which do not have availability. The purpose of the PRIVATE_DEPARTURES_NOT_AVAILABLE flag is to indicate that a certain trip cannot be offered as a private group.
duration required	Integer	The length of the tour in days
start_location read-only	Reference Object	The starting location of tour
end_location read-only	Reference Object	The ending location of the tour
meals_included required	Nested Object	Information about the number of meals included in the tour
breakfast required	Integer	The number of breakfasts included in the tour
lunch required	Integer	The number of lunches included in the tour
dinner required	Integer	The number of dinners included in tour
meals_budget required	Nested Object	Information about the budget for meals that are not included
amount_range required	Field	The minimum and maximum amount for meals not included, as a list of two numbers
currency required	String	The currency of the meal budget
details required	Field	Additional descriptive details about an itinerary classified by type
body required	String	The description of the itinerary detail
type required	Nested Object	The classification of the detail
id read-only	String
name required	String	A short descriptive label.
code required	String	A unique code for this detail type
packing_lists required	Field
id read-only	String
href read-only	Field
name required	String	A label describing the dossier this packing list is meant for
images required	Field	A list of images associated with this itinerary
id read-only	String
href read-only	Field
file required	Nested Object	Data about the image file
url required	String	The absolute url where the image can be found
type required	String	The type of the image. Can be one of “MAP” or “OTHER”
media read-only	Field
highlights read-only	Field
valid_during_ranges required	Field	The date ranges when this itinerary variation is valid
start_date required	Date	The first day of a range when this itinerary variation is valid
end_date required	Date	The last day of a range when this itinerary variation is valid
variations required	Field	The different variations of this itinerary
id required	String	The unique identifier for the itinerary of this variation
variation_id required	String	The unique identifier of a specific variation of this itinerary
href read-only	Field
valid_during_ranges required	Field	The date ranges when this itinerary variation is valid
start_date required	Date	The first day of a range when this itinerary variation is valid
end_date required	Date	The last day of a range when this itinerary variation is valid
days required	Field	The day-by-day description of the tour
id read-only	String
day required	Integer	The day number within the itinerary
label required	String	A location or activity based label for the day
summary required	String	A summary description of the day
description required	String	A detailed description of the day
instructions required	String	Additional notes, instructions or tips about the day needed when on the trip
start_location read-only	Reference Object	The starting location of the day
end_location read-only	Reference Object	The ending location of the day
meals required	Field	Included meals for this day
type required	String	The type of the included meal. Can be one of BREAKFAST, LUNCH or DINNER
description required	String	An optional description of the included meal
components required	Field	A list of component (activities and transports) for the day
type required	String	The type of the component. Can be one of ACCOMMODATION, ACTIVITY, TRANSPORT or FREE_TIME
start_location read-only	Reference Object	The starting location for this component
end_location read-only	Reference Object	The ending location for this component
summary required	String	A summary description of the component
description required	String	A detailed description of the component
instructions required	String	Additional notes, instructions or tips about the component needed when on the trip
accommodation_dossier required	Nested Object	A reference to an accommodation dossier resource for the component (if applicable). This is a representative accommodation for that day of the itinerary, and as such is not necessarily the accommodation used for all departures
id read-only	String
href read-only	Field
name required	String	The name of the accommodation
property_type required	Nested Object	The type of this accommodation
code required	String	The code for the property type
label required	String	The human-friendly label for the property type
activity_dossier read-only	Reference Object	A reference to an activity dossier resource for the component (if applicable)
transport_dossier read-only	Reference Object	A reference to a transport dossier resource for the component (if applicable)
transport_leg_dossier read-only	Reference Object	A reference to a transport leg dossier resource for the component (if applicable)
duration required	Nested Object	The duration of this component
min_hr required	String	The minimum duration of this component expressed as a decimal number
max_hr required	String	The minimum duration of this component expressed as a decimal number
distance_km required	Integer	The distance of this component (in kilometers)
start_time required	String	The starting time of this component (in hh:mm format)
end_time required	String	The ending time of this component (in hh:mm format)
time_period required	String	The time period of the component. Can be one of MORNING, AFTERNOON, EVENING of FULL_DAY
is_overnight required	Boolean	Flag to indicate if the transport component is continuing overnight into the next day
optional_activities required	Field	A list of optional activities for the day
activity_dossier required	Nested Object	A reference to an activity dossier resource for the optional activity
id read-only	String
href read-only	Field
name required	String	The name of the activity
site_links	Field	Itinerary-related links pointing to gadventures.com
type required	String	The classification of the link. Possible values: * DETAILS * OVERVIEW * PRICING * DETAILS_PDF
href required	String	The fully qualified URL of the site link.
publish_state	Choice	The state or online status of this itinerary
ripple_score	Nested Object	The Ripple Score for an Itinerary. This is calculated based off the amount of money that stays locally. The score ranges between 0-100
score required	Integer	The Ripple Score for a specific Itinerary
start_date required	Date	The first day of a range when this score is valid
end_date required	Date	The last day of a range when this score is valid

Get an Itinerary

GET /itineraries/(string: itinerary_id)/¶

Get an Itinerary Variation

GET /itineraries/(string: itinerary_id)/(string: variation_id)/¶