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:

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)
flags read-only Multiple Choice For itineraries visiting Machu Picchu in Peru, the presence of these flags indicate 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). For itineraries that do not visit Machu Picchu the list of flags will be empty.
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.
booking_companies Field The booking companies that provide this tour.
  • id read-only
String  
  • href read-only
Field  
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)/