Departures

This resource represents a specific instance of a tour_dossier, with start/finish dates & locations. A departure is the core product and is required for any new booking. Departures can be referenced using the SKU. This is a generalized term used across products, but in the context of tour_dossier departures, it is synonymous with the travel industry standard term “Trip Code”.

The Departure resource references the tour_dossier resource. Be aware that although rare, it is possible for the related tour_dossier to change. This occurs when new seasonal tours are published and become more appropriate for a group of departures.

Availability

First, all departures represented in the G API are Guaranteed to Depart. Guaranteed Departures are a mandate set by G Adventures, and that applies to all departures, regardless of situation.

If a Departure is available for sale (free sell would be an industry term), a customer can be booked on it with no restrictions on space. It is acknowledged that if a Departure is marked as AVAILABLE, a customer can be booked on it.

However, there are situations where a departure may be marked as Request Space or Waitlisted. These require additional confirmation or waiting in a queue, respectively to confirm a hold of space on that Departure.

For full definitions of availability, we recommend our Availability documentation.

Reading & Booking Rooms

In some cases, multiple rooming options are available for a departure. For example, cruising and sailing tour_dossiers usually have various cabin options. These options are represented as list of rooms objects. When multiple objects are present in this field, the “code” value is required as input when POSTing a new departure service.

For consistency, land-based departures are also represented this way, but there will only ever be one object in the rooms list, with a code value of STANDARD. In this case, the code is not required when POSTing a new departure service. The departure list view contains critical in-line information about availability, lowest pricing, start/finish date, etc… for convenience of implementations. This allows clients to reduce the number of requests for common use cases.

For example, a tour_dossier landing page on a website often contains a list view with only the critical information about a departure. Additional details such a add ons, special child pricing, single supplement charge, etc… are only needed when a particular departure is chosen. As such, we encourage implementations that don’t rely on the detail view of a departure to be stored or cached in advance. If all data is needed for an implementation, we encourage the use of Webhooks.

Multiple Instances

For particularly popular Departures, it may run under multiple instances. When a Departure runs multiple instances, it’s running on the same date as another, but is part of a completely different tour group and CEO.

This can be identified by reviewing the sku, and identifying an increment on the final number. For example, a Departure may have a sku of GAPSZCY170224-O1. A second instance of this Departure would be incremented to GAPSZCY170224-O2.

These should be treated as unique Departures and sold individually. The only relation they have is operating on the same day, but are otherwise identified uniquely. It is always recommended to use the resource id for unique identification.

XML Schema:

GET /departures/(string: departure_id)

Resource Definition

Note

This resource can be searched, allowing to you to access a filtered set of data. See our Searching The G API documentation for details on how to query specific fields and the operators available.

Fields

Name

Type

Description

id read-only

String

href read-only

Field

date_created

Datetime

The time when the resource was created, in the standard Dates & Times.

date_last_modified

Datetime

The time when the resource was last modified, in the standard Dates & Times.

name required

String

The name of this resource.

product_line required

String

A 1 to 10 character sequence for the tour associated wih this product.

sku required

String

A unique code for this product. The first 3 letters represent the brochure code. The next 1 to 10 characters represent the dossier code. The following 6 digits represent the start date of the product, in the format %YY%mm%dd. The final 3 characters represent the product instance code, for cases where there are multiple products of the same tour on the same day.

booking_companies read-only

Field

The booking_company that own this product, and are in charge of its inventory and sale.

  • id read-only

String

  • href read-only

Field

  • name read-only

String

Company name

start_date required

Date

The date this product begins, in the standard Dates & Times.

finish_date required

Date

The date this product ends, in the standard Dates & Times.

date_cancelled required

Datetime

The datetime in which this Departure become no longer available, and thus cancelled. This is not the same as being sold out. Departure’s can be cancelled prior to having any booked passengers.

flags required

List

A list of codes that, when present, require special considerations when booking a services on this departure.

  • FULL_PAYMENT_REQUIRED_TO_BOOK: Full payment is required to book a services on this departure.

  • INCA_TRAIL: This Departure is slated to go on the Inca Trail. The presence of this flag does not confirm the availability of the Inca Trail (See other flags below), but rather, confirms it’s an option available at booking time.

  • INCA_CLOSURE: The Inca Trail is closed for annual maintenance during this departure.

  • CLOSED_INCA_TRAIL___SO: Inca Trail permits are Sold Out for this departure and cannot be requested.

  • CLOSED_INCA_TRAIL___OR: Inca Trail permits are On Request for this departure and cannot be guaranteed.

  • ARRIVAL_TRANSFER_INCLUDED: Arrival transfer is included in the departure. No arrival transport addons are available.

  • DEPARTURE_TRANSFER_INCLUDED: Departure transfer is included in the departure. No departure transport addons are available.

  • NOT_GUARANTEED: The number of passengers on this departure is less than the threshold to guarantee that the departure will run.

  • GUARANTEED: The number of passengers on this departure has reached the threshold to guarantee that the departure will run.

  • DEFAULT_ARRIVAL_TIME: The passenger can arrive at any time on the first day of the tour. It this flag is absent, then there is a latest time at which the passengers must join the group on the first day, which is described in the latest_arrival_time field.

  • DEFAULT_DEPARTURE_TIME: The passenger can leave at any time on the last day of the tour. It this flag is absent, then there is an earliest time at which the passengers can depart from the group on the last day, which is described in the earliest_departure_time field.

start_address required

Nested Object

Start Location information for the product.

  • street required

String

Street of this location.

  • city required

String

City of this location.

  • country required

Nested Object

Country resource associated with this location.

    • id read-only

String

    • href read-only

Field

    • name

String

  • postal_zip required

String

The postal/zip code of this location.

  • latitude

Decimal

A geographic coordinate that specifies the north-south position of a point on the Earth’s surface (valid values range from -90.0 to 90.0)

  • longitude

Decimal

A geographic coordinate that specifies the east-west position of a point on the Earth’s surface (valid values range from -180.0 to 180.0)

finish_address required

Nested Object

Finish Location information for the product.

  • street required

String

Street of this location.

  • city required

String

City of this location.

  • country required

Nested Object

Country resource associated with this location.

    • id read-only

String

    • href read-only

Field

    • name

String

  • postal_zip required

String

The postal/zip code of this location.

  • latitude

Decimal

A geographic coordinate that specifies the north-south position of a point on the Earth’s surface (valid values range from -90.0 to 90.0)

  • longitude

Decimal

A geographic coordinate that specifies the east-west position of a point on the Earth’s surface (valid values range from -180.0 to 180.0)

latest_arrival_time required

Date

The latest time that the traveller’s flight can arrive at the nearest_start_airport for this product, in the standard Dates & Times.

earliest_departure_time required

Date

The earliest time that the traveller’s flight can depart at the nearest_finish_aiport for this product, in the standard Dates & Times.

nearest_start_airport

Nested Object

  • code required

String

The nearest airport to the start location for this product, using the standard International Air Transport Association (IATA) airport codes.

nearest_finish_airport

Nested Object

  • code required

String

The nearest airport to the finish location for this product, using the standard International Air Transport Association (IATA) airport codes.

tour read-only

Reference Object

The tour of this product.

tour_dossier read-only

Reference Object

The tour dossier resource associated with this departure.

rooms required

Field

A list of available rooming options.

  • code required

String

A unique code for this room that is used when creating a booking. This code will never change and can be used as an identifier.

  • name required

String

The name of this room.

  • flags required

Field

Currently, always an empty list.

  • availability required

Nested Object

Availability information for this room option of this product. See our availability reference here: Availability.

    • status required

String

The availability status indicates whether or not this room option on this product can be booked, as well as the resulting status of a booked services on this product. A list of availability statuses can be found here: Availability

    • total required

Integer

The total number of available spaces for this room option on this product. This includes male/female-only spaces.

    • male required

Integer

The number of male-only available spaces for this room option on this product. For products with shared rooming (e.g. cruises, ships, etc), this value is important for single travellers booking into one of the last remaining rooms (on a shared basis) that is already partially occupied by a male traveller.

    • female required

Integer

The number of female-only available spaces for this room option on this product. For products with shared rooming (e.g. cruises, ships, etc), this value is important for single travellers booking into one of the last remaining rooms (on a shared basis) that is already partially occupied by a female traveller.

  • price_bands required

Field

Pricing information for this room option on this product.

    • code required

String

A unique code for this Pricing option. Possible values are: ‘ANY’, ‘ADULT’, ‘CHILD’, ‘INFANT’.This code will never change and can be used as an identifier.

    • name required

String

The name of this Pricing option. This is usually a string representation of the minimum/maximum ages for this Pricing option (e.g. Adult, Child, Infant, etc).

    • min_travellers required

Integer

The minimum number of travellers that must book this room option on this product to receive this Pricing option.

    • max_travellers required

Integer

The maximum number of travellers that can book this room option on this product to receive this Pricing option.

    • min_age required

Integer

The minimum age of a traveller (on the start date of this product) that can receive this Pricing option.

    • max_age required

Integer

The maximum age of a traveller (on the start date of this product) that can receive this Pricing option.

    • prices required

Field

The prices for this price_band.

      • currency required

String

The currency ISO code, in the standard Currencies & Prices.

      • amount required

Decimal

The amount for this Pricing option, in the standard Currencies & Prices.

      • deposit required

Decimal

The deposit amount needed as a payment before a booked services on this product and Pricing option can be confirmed, in the standard Currencies & Prices.

      • promotions required

Field

A list of promotions associated with this product. As expected, a promotions Webhooks will fire when it is modified. Clients should then iterate through the list of promotion ‘products’ in order to pull new promotional pricing data. The best promotions (largest discount) are displayed first.

        • id read-only

String

        • href read-only

Field

        • amount required

Decimal

The promotion amount for this Pricing option, in the standard Currencies & Prices.

  • addons required

Field

    • product required

Nested Object

A reference to the product itself, and some minimal data.

      • id read-only

String

      • href read-only

Field

      • name required

String

Name of the add-on; e.g. for hotels, the hotel name.

      • type required

String

Name of the add-on; e.g. for hotels, the hotel name.

      • sub_type required

String

The add-on category: Hotel, Transfer, Flight, Single Supplement

    • start_date required

Date

The earliest date a booked services on the product can begin.

    • finish_date required

Date

The latest date a booked services on the product can begin.

    • min_days required

Integer

The minimum number of days a booked services on this product can span.

    • max_days required

Integer

The maximum number of days a booked services on this product can span.

    • request_space_date required

Date

Services booked on this product after this date will have status On Request.

    • halt_booking_date required

Date

The latest date a services may be booked on this product.

addons

Field

  • product required

Nested Object

A reference to the product itself, and some minimal data.

    • id read-only

String

    • href read-only

Field

    • name required

String

Name of the add-on; e.g. for hotels, the hotel name.

    • type required

String

Name of the add-on; e.g. for hotels, the hotel name.

    • sub_type required

String

The add-on category: Hotel, Transfer, Flight, Single Supplement

  • start_date required

Date

The earliest date a booked services on the product can begin.

  • finish_date required

Date

The latest date a booked services on the product can begin.

  • min_days required

Integer

The minimum number of days a booked services on this product can span.

  • max_days required

Integer

The maximum number of days a booked services on this product can span.

  • request_space_date required

Date

Services booked on this product after this date will have status On Request.

  • halt_booking_date required

Date

The latest date a services may be booked on this product.

availability

Nested Object

Availability information for this room option of this product. See our availability reference here: Availability.

  • status required

String

The availability status indicates whether or not this room option on this product can be booked, as well as the resulting status of a booked services on this product. A list of availability statuses can be found here: Availability

  • total required

Integer

The total number of available spaces for this room option on this product.

lowest_pp2a_prices

Field

The lowest Adult price per person (based on double occupancy) for this departure across all rooms, per currency. Note that this could be price for a room that doesn’t have free spaces anymore.

  • currency required

String

The currency ISO code, in the standard Currencies & Prices.

  • amount required

Decimal

The amount for this Pricing option, in the standard Currencies & Prices.

local_payments

Field

For specific departures, travellers are expected to have cash available in a specific currency to cover local fees. For example, this may be the entry fee to a park which is part of the itinerary. This information should be exposed to passengers as part of the itinerary details, and it varies by departure.

  • amount required

Decimal

The amount in the specified currency this payment costs.

  • currency required

String

The currency this payment is expected to be paid in.

  • label required

String

A label explaining the payment which can be presented to the traveller.

travel_ready_policy

Nested Object

The Travel Ready Policy associated with this Departure

  • code required

String

The normalized value for the type of this Travel Ready Policy. Possible values are:

  • COVID_VACCINATED: Must be fully vaccinated 14 days prior to the start date to travel on this departure

  • COVID_VACCINATED_OR_PCR_TEST: Must be vaccinated or have a negative PCR test within 4 days of the start date to travel on this departure.

  • NO_POLICY: There is no travel-ready-policy associated with this departure.

  • name required

String

The name of this Travel-Ready Policy.

requirements required

Field

A list of requirements that must be met before a services on this product can be booked or confirmed. A list of requirements can be found here: Booking Requirements

  • type required

String

The requirement category. ‘CHECKIN’ means the requirement must be met before a voucher document resource can be generated for a booked services on this product. ‘CONFIRMATION’ means the requirement must be met in order to confirm a booked services.

  • name required

String

The name of this requirement.

  • code required

String

A unique code for this requirement. This code will never change and can be used as an identifier.

  • message required

String

A message describing that data needed to fulfill this requirement.

  • flags required

Field

A list of codes that provide additional information related to this requirement:

  • INTERNAL: This requirement must be fulfilled internally by our staff. When this flag is absent, the requirement can be fulfilled by updating the appropriate value(s) in either the customer or services resource.

  • details required

Field

A list of informational details for this requirement. This is information that should be given to the customer when booking a services on this product.

    • summary required

String

A brief description of this detail.

    • description required

String

A full description of this detail.

    • detail_type required

Nested Object

A type of this detail.

      • code required

String

A unique code for this detail type. Possible values are: ‘CONFIRMATION_ONLY’, ‘ANY’. CONFIRMATION_ONLY means this detail is relevant for confirmations. ANY means this detail is relevant for any type of communication.

components read-only

Field

A departure component is made of components that detail the included accommodations, activities, and transports.

structured_itineraries required

Field

A list of itineraries for this departure.

  • id read-only

String

  • variation_id read-only

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

Date

The last day of a range when this itinerary variation is valid

relationships required

Field

Relationships list the related departures that are available to be sold along side this departure. These related departures will be defined by their type and sub_type values.

  • type required

String

The type of this relationship. Possible values are: * MINI_ADVENTURE* DAY_TOUR

  • sub_type required

String

The sub_type of this relationship. Possible values are: * null: This implies no sub-type * PRE_TOUR: This product is available before this departure * POST_TOUR: This product is availble after this departure

  • departure required

Nested Object

The related departure assigned to this departure.

    • id read-only

String

    • href read-only

Field

    • start_date required

Date

The date this product begins, in the standard Dates & Times.

program

String

Generally referencing another tour code, this identifies an internal code that is used to group together Departures after the reservation process. As a consumer of the API, you would only use this field if you were doing reservation sheet integrations.

Non-Rooming Departure

Rooming Departure