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)

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)/