Basic Trip Concepts
This page provides useful information about trip concepts and the Trip APIs.
What is a Trip?
A trip refers to a travel itinerary booked and managed via the Spotnana platform. It functions as a central object that groups and manages all your travel bookings including airline tickets, hotel stays, car rentals, limo services, rail tickets, and other miscellaneous bookings.
Fig: Visual representation of a trip in Spotnana.
In our APIs, a trip can be represented using the following fields:
-
tripId: A unique ID assigned to a trip at the time of booking. -
tripName: A name for your trip that you can provide on the checkout page of your travel booking. ThetripNameandtripIdcan be used to differentiate between other active trips or to add more bookings to an existing trip. -
tripDescription: An additional text field used to provide more details about your upcoming trip. -
startDateandendDate: The start and end dates of the entire trip itinerary. These fields will take into account all your bookings (air, rail, hotel, car, limo, and miscellaneous) within the sametripIdand will assign thestartDateandendDatebased on when you begin and end your journey.-
For example, let's assume your first flight to a conference leaves on 29th September, 2024 at 9:50 AM and your return flight lands at your destination on 5th October, 2024 at 3:10 AM. Additionally, you've also booked a hotel room during your stay between 30th September to 4th October, 2024. In this scenario, the trip
startDatewill be2024-09-29T09:50:00and theendDatewill be2024-10-05T03:10:00.Note: The date and time are represented in ISO 8601 format across all the APIs.
-
For example, let's assume your first flight to a conference leaves on 29th September, 2024 at 9:50 AM and your return flight lands at your destination on 5th October, 2024 at 3:10 AM. Additionally, you've also booked a hotel room during your stay between 30th September to 4th October, 2024. In this scenario, the trip
You can create a new trip using the Create Trip API or using the Spotnana Online Booking Tool (OBT).
Use the tripId to associate all the bookings (air, rail, hotel, car, limo, and miscellaneous) with a specific trip.
Note: To understand when to use the Create Trip API for air bookings, refer to the air booking workflow.
Concepts
This section provides definitions for some concepts that are used when working with trips.
PNR
A Passenger Name Record (PNR) refers to the record of a travel booking made on Spotnana.
For every individual air, hotel, car, limo, rail, and miscellaneous booking made on our platform, a PNR is created.
This PNR can then be used to refer to that booking.
A tripId represents the entire itinerary for your travel. Each tripId can contain multiple PNRs.
Every PNR is created with a unique pnrId on the Spotnana platform.
You can access the details of the PNR later using the Get PNR
API by providing the pnrId and tripId as request parameters.
Note: On the Spotnana Online Booking Tool (OBT) a PNR is referred to as a Booking ID.
Source PNR
For bookings made via the Spotnana platform, "source" refers to either the Global Distribution System (GDS) or the New Distribution Capability (NDC) source where the record was created. The Source PNR is used on the Spotnana platform to store the booking record created at the respective source.
The Source PNR is contained in the sourcePnrId field of our APIs and can be accessed using
the Get trip details API.
In the API response, navigate to pnrs > data > sourceInfo to get the sourcePnrId and all its associated information.
Vendor Confirmation Number
The Vendor Confirmation Number is a booking record created by the supplier (e.g., service providers such as airlines, hotels, car rental companies and rail service providers). The service provider creates a confirmation code within their database to maintain a record of your booking. For example, in an air booking, the vendor confirmation number (or Airline confirmation) is the code you’d use to check in for your flight.
This booking record is stored in the vendorConfirmationNumber field in our APIs.
Every pnrId created by Spotnana will contain an associated vendorConfirmationNumber for the booking.
You can find this information in the Get trip details API
under pnrs > data within the respective booking objects (airPnr, hotelPnr, carPnr, limoPnr, and miscPnr).
For rail bookings, the record is stored as pnrs > data > railPnr > sections > vendorConfirmations > vendorConfirmationId.
Shell PNR
A travel agent may sometimes prefer to create a booking directly on the Global Distribution System (GDS). In those cases, a shell PNR in Spotnana is used to track the booking information that was created directly on the GDS. Once the Shell PNR is created on Spotnana, agents can use it to add bookings via the GDS.
All information about the booking made in the GDS for the Shell PNR is tracked using the
pendingShellPnrs > data > sourceInfo > sourcePnrId field in the Get trip details API response.
The pendingShellPnrs field indicates that the Shell PNR is in a pending state.
Once the PNR has been confirmed from the GDS, the data will be moved into pnrs > data.
Manual Form PNR
A Manual Form PNR refers to a booking record created directly on the supplier’s website (offline). A travel agent can create a booking directly with the supplier and then manually submit the booking details into Spotnana. Manual Form PNRs can also be used as an alternative to GDS passive segment booking.
A pending manual form PNR is tracked using the pendingManualFormPnrs field
in the Get trip details API response.
Once the manual form PNR is finalized, the data will be moved into pnrs > data.
Simple PNR
A Simple PNR is a lightweight record designed to provide essential booking (air, rail, hotel, and car) information
when the standard mapping between the Source PNR and the Spotnana PNR encounters any unexpected error.
This ensures that Spotnana has atleast the bare minimum information for a booking even if there's a mapping error.
The Simple PNR data can be found in simplePnrs field of the Get trip details API response.
Travel Services
Our platform currently supports travel booking options for air, car rentals, hotels, rail, and limo service.
When you are making any of these bookings on Spotnana, a pnrId will keep track of all the data associated with the booking.
For example, when making an air booking, information such as the leg details, airline information, traveler information,
Special Service Requests (SSR), and other details are tracked under the unique pnrId.
In the Get trip details or the Get PNR API, the data for each travel service is captured using the following fields:
-
airPnr: Stores all information related to an air booking. -
hotelPnr: Stores all information related to a hotel booking. -
carPnr: Stores all information related to a car rental booking. -
railPnr: Stores all information related to a rail booking. -
limoPnr: Stores all information related to a limo service booking. -
miscPnr: Stores information related to any other miscellaneous services booked as part of a trip.
A pnrId can be associated with any one of the above mentioned services offered.
For example, when you make an air booking, the airPnr data is created within the booking’s pnrId.
Traveler Index
For air bookings, a single PNR can hold information for multiple travelers and their respective ticket prices.
For example, in an Air PNR, the ticket price of an adult traveler might be different from an infant traveler.
The traveler index in our APIs is used to represent each traveler associated with a PNR and
The traveler index data can be found in the pnrs > data > airPnr > travelerInfos > travelerIdx field
in the Get trip details API response.
Air Ticket
In air bookings, a traveler can hold multiple tickets.
For example, some airlines create separate tickets for the air booking and ancillaries.
So, a traveler may have two or more tickets associated with their traveler index.
The details of each ticket associated with the traveler can
be found in the pnrs > data > airPnr > travelerInfos > tickets field
of the Get trip details API response.
Fig: Visual representation of air tickets
Out of Policy Booking
Based on your organization's policies, a traveler might be allowed to make an out of policy booking.
In such cases, the PNR will contain the out of policy data and it can be accessed using
the Get trip details API or
the Get PNR API in the policyInfo > outOfPolicy field.
If outOfPolicy is set to true, then the respective reasonCode and reason text are also stored for the booking.