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. |
|
String |
|
|
Field |
|
|
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 service on this departure.
|
start_address required |
Nested Object |
Start Location information for the product. |
|
String |
Street of this location. |
|
String |
City of this location. |
|
Nested Object |
Country resource associated with this location. |
|
String |
|
|
Field |
|
|
String |
|
|
String |
The postal/zip code of this location. |
|
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) |
|
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. |
|
String |
Street of this location. |
|
String |
City of this location. |
|
Nested Object |
Country resource associated with this location. |
|
String |
|
|
Field |
|
|
String |
|
|
String |
The postal/zip code of this location. |
|
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) |
|
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 |
|
|
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 |
|
|
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. |
|
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. |
|
String |
The name of this room. |
|
Field |
Currently, always an empty list. |
|
Nested Object |
Availability information for this room option of this product. See our availability reference here: Availability. |
|
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 |
|
Integer |
The total number of available spaces for this room option on this product. This includes male/female-only spaces. |
|
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. |
|
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. |
|
Field |
|
|
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. |
|
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). |
|
Integer |
The minimum number of travellers that must book this room option on this product to receive this Pricing option. |
|
Integer |
The maximum number of travellers that can book this room option on this product to receive this Pricing option. |
|
Integer |
The minimum age of a traveller (on the start date of this product) that can receive this Pricing option. |
|
Integer |
The maximum age of a traveller (on the start date of this product) that can receive this Pricing option. |
|
Field |
The prices for this price_band. |
|
String |
The currency ISO code, in the standard Currencies & Prices. |
|
Decimal |
The amount for this Pricing option, in the standard Currencies & Prices. |
|
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 & Prices. |
|
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. |
|
String |
|
|
Field |
|
|
Decimal |
The promotion amount for this Pricing option, in the standard Currencies & Prices. |
|
Field |
|
|
Nested Object |
A reference to the product itself, and some minimal data. |
|
String |
|
|
Field |
|
|
String |
Name of the add-on; e.g. for hotels, the hotel name. |
|
String |
Name of the add-on; e.g. for hotels, the hotel name. |
|
String |
The add-on category: Hotel, Transfer, Flight, Single Supplement |
|
Date |
The earliest date a booked service on the product can begin. |
|
Date |
|
|
Integer |
The minimum number of days a booked service on this product can span. |
|
Integer |
The maximum number of days a booked service on this product can span. |
|
Date |
Services booked on this product after this date will have status On Request. |
|
Date |
|
addons |
Field |
|
|
Nested Object |
A reference to the product itself, and some minimal data. |
|
String |
|
|
Field |
|
|
String |
Name of the add-on; e.g. for hotels, the hotel name. |
|
String |
Name of the add-on; e.g. for hotels, the hotel name. |
|
String |
The add-on category: Hotel, Transfer, Flight, Single Supplement |
|
Date |
The earliest date a booked service on the product can begin. |
|
Date |
|
|
Integer |
The minimum number of days a booked service on this product can span. |
|
Integer |
The maximum number of days a booked service on this product can span. |
|
Date |
Services booked on this product after this date will have status On Request. |
|
Date |
|
availability |
Nested Object |
Availability information for this room option of this product. See our availability reference here: Availability. |
|
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 |
|
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. |
|
String |
The currency ISO code, in the standard Currencies & Prices. |
|
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. |
|
Decimal |
The amount in the specified currency this payment costs. |
|
String |
The currency this payment is expected to be paid in. |
|
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 |
|
String |
The normalized value for the type of this Travel Ready Policy. Possible values are:
|
|
String |
The name of this Travel-Ready Policy. |
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 |
|
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. |
|
String |
The name of this requirement. |
|
String |
A unique code for this requirement. This code will never change and can be used as an identifier. |
|
String |
A message describing that data needed to fulfill this requirement. |
|
Field |
A list of codes that provide additional information related to this requirement: |
|
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. |
|
String |
A brief description of this detail. |
|
String |
A full description of this detail. |
|
Nested Object |
A type of this detail. |
|
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. |
|
String |
|
|
String |
The unique identifier of a specific variation of this itinerary |
|
Field |
|
|
Field |
The date ranges when this itinerary variation is valid |
|
Date |
The first day of a range when this itinerary variation is valid |
|
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 |
|
String |
The type of this relationship. Possible values are: * MINI_ADVENTURE* DAY_TOUR |
|
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 |
|
Nested Object |
|
|
String |
|
|
Field |
|
|
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. |