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)

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-time.
date_last_modified Datetime The time when the resource was last modified, in the standard dates-time.
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 companies 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-time.
finish_date required Date The date this product ends, in the standard dates-time.
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 service on this departure.

  • FULL_PAYMENT_REQUIRED_TO_BOOK: Full payment is required to book a service on this departure.
  • NO_OPTIONS: service must be confirmed at time of booking, options can not be held 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.
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-time.
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-time.
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 Nested Object The tour of this product.
tour_dossier read-only Nested 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 service 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.
      • amount required
Decimal The amount for this pricing option, in the standard currencies.
      • deposit required
Decimal The deposit amount needed as a payment before a booked service on this product and pricing option can be confirmed, in the standard currencies.
      • 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.
  • 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 service on the product can begin.
    • finish_date required
Date The latest date a booked service on the product can begin.
    • min_days required
Integer The minimum number of days a booked service on this product can span.
    • max_days required
Integer The maximum number of days a booked service 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 service 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 service on the product can begin.
  • finish_date required
Date The latest date a booked service on the product can begin.
  • min_days required
Integer The minimum number of days a booked service on this product can span.
  • max_days required
Integer The maximum number of days a booked service 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 service 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 service 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 available rooms, per currency.
  • currency required
String The currency ISO code, in the standard currencies.
  • amount required
Decimal The amount for this pricing option, in the standard currencies.
requirements required Field A list of requirements that must be met before a service 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 service on this product. ‘CONFIRMATION’ means the requirement must be met in order to confirm a booked service.
  • 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 service 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 service 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 required
Date The last day of a range when this itinerary variation is valid

Non-Rooming Departure

Rooming Departure