openapi: "3.0.0"
info:
version: "4.15.0"
title: Trip Ninja API Documentation
description: |
<h2>Introduction</h2>
Trip Ninja uses a REST API with requests and responses in JSON format. For development and testing, the pre-production servers
are to be used. Once ready for live use, access to the production servers will be provided. All search endpoints have both production
and pre-production endpoints - these correspond to the GDS’s production and pre-production services, and can be used as desired.<br />
<h2>Trip Ninja API URLs</h2>
Pre-Production: https://preprodapi.tripninja.io
For security, Trip Ninja’s servers are only accessible from whitelisted IPs. Please contact your account manager to whitelist IPs you
will be using.
Before you start ensure that:<br />
- IP addresses have been provided to be whitelisted for our servers.<br />
- PCC / OfficeID emulation via Trip Ninja’s PCC/OfficeID has been set up.<br />
- API username and password have been provided by Trip Ninja.<br />
<h2>FareStructure</h2>
The FareStructure product returns the set of best GDS responses that create the specified route. It finds the best fare structure via
split ticketing and does not reorder the destinations. Each of the returned segments must be ticketed in its own PNR. <br><br>The “structure” seen in the
FareStructure response determines how you will carry out price confirmation as well as PNR creation. We start counting flights at 0.
For example if structure is [[0, 2] , 1], this implies flight 0 and flight 2 are to be priced/ticketed together as one openjaw.
Flight 1 should be priced as a oneway. [1, 2, 3] would be 3 separate oneways to be priced/ticketed individually.
[[0, 1], [2, 3]] would be two openjaws, flight 0 and flight 1 priced/ticketed together as one openjaw and flights
2 and 3 ticketed together as one openjaw.
<h2>Workflow</h2>
The following diagram shows the typical data flow of API calls to Trip Ninja for a FareStructure integration with both a partner website
and metasearch as sources.
Note: the following three endpoints (Price Confirmation, PNR Creation, Ticket Issuance) are simply to report to us that you have done these API calls to your GDS.
Price Confirmation, PNR creation, and Ticket Issuance should follow your existing process (as per the following diagram).
<h2>Authentication</h2>
Trip Ninja uses Basic Authentication standards. Simply encode your username and password string using base64 and pass it in the
authorization headers. See the python example below on how this is done. In the example, the payload and API endpoint url are not
shown.
Python Example:
<pre>
import base64
auth = base64.b64encode("USERNAME:PASSWORD")
headers = {
'authorization': "Basic "+ auth,
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
</pre>
# Error Codes
<table>
<tr><td>IE01</td><td>Need minimum 2 destinations</td></tr>
<tr><td>IE02</td><td>Duplicate city in list</td></tr>
<tr><td>IE09</td><td>Can't run any queries for flight dates in the past</td></tr>
<tr><td>IE10</td><td>Incorrect city_type, expected one of ['C', 'A']</td></tr>
<tr><td>IE16</td><td>Please provide a PCC</td></tr>
<tr><td>IE17</td><td>Invalid carrier</td></tr>
<tr><td>IE19</td><td>Incorrect region, expected one of 'emea', 'apac', 'americas', 'edge'</td></tr>
<tr><td>IE20</td><td>Incorrect provider, expected one of '1V','1G','1P','1A'</td></tr>
<tr><td>IE21</td><td>Wrong currency</td></tr>
<tr><td>IE22</td><td>Not a valid cabin option. expected one of 'E' , 'PE', 'SE', 'BC','FC', 'PFC'</td></tr>
<tr><td>IE23</td><td>Not a valid alliance. Expected one of *A, *S, *O</td></tr>
<tr><td>IE24</td><td>Travellers Type does not meet expected criteria. Should be a list having between 0 and 10 values</td></tr>
<tr><td>IE26</td><td>Exclude_carriers, alliance and permitted_carriers are mutually exclusive - please choose one</td></tr>
<tr><td>IE27</td><td>Num_results should be an integer between 50 and 5000</td></tr>
<tr><td>IE28</td><td>Refundable parameter must be boolean value true or false</td></tr>
<tr><td>IE29</td><td>Invalid Traveller type</td></tr>
<tr><td>IE30</td><td>Incorrect value for single_pnr, must be boolean</td></tr>
<tr><td>IE31</td><td>LCC token not associated with user</td></tr>
<tr><td>IE32</td><td>Incorrect value for include_itineraries, must be boolean</td></tr>
<tr><td>IE33</td><td>Stops must be one of 'any', 'direct', '1', '2'</td></tr>
<tr><td>IE34</td><td>Incorrect value for no_overnight_layovers, must be boolean</td></tr>
<tr><td>IE36</td><td>Invalid LCC name</td></tr>
<table>
x-logo:
url: 'https://s3.amazonaws.com/tn-api-docs/trip_ninja_logo.png'
altText: Trip Ninja logo
href: 'https://www.tripninja.io/'
servers:
- url: https://preprodapi.tripninja.io
description: Pre-Production server
paths:
/search/flights/{endpoint}/:
post:
parameters:
- in: path
name: endpoint
required: true
schema:
type: string
enum: [preprod, prod]
description: Parameter toggles Data Source production and pre-production endpoints
summary: "Flight Search"
description: |
This endpoint triggers FareStructure for any number of city search
Please note that the "total_cost" field and "price" fields in the response do not contain the markup amount. The "total_cost" field is only to display the cheapest trip in the results.
The "price" fields displayed at the itinerary or segment level do not include the markup amount either. When displaying the trip costs using "include_itineraries" = true, use the
"price" at the itinerary level plus the "tn_net_fare_markup" amount. If using the segment response type, add the "price" value for each of the segments chosen for the trip plus the "tn_net_fare_markup"
amount to get the total trip price.
Additionally, two optional parameters alter the structure of the response. include_itineraries
and route_flexible both change the structure when passed as true. See the fields description for
details and examples have been provided in the Response Samples section.
operationId: FlightSearch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FlightSearchRequest'
responses:
200:
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SegmentFSSearchResponse'
- $ref: '#/components/schemas/SegmentFSSearchResponseWithFlexTrip'
- $ref: '#/components/schemas/ItineraryFSSearchResponse'
- $ref: '#/components/schemas/ItineraryFsSerachResposneWithFlexTrip'
400:
description: Invalid Input
content:
application/json:
schema:
type: object
properties:
status:
type: sting
description: Error code and 0 for success response
example: IE23
message:
type: string
description: Contains the error message
example: Not a valid alliance. Expected one of *A, *S, *O
401:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: sting
description: Error code and 0 for success response
example: IE44
message:
type: string
description: Contains the error message
example: "User is not authorized"
206:
description: Partial Content (Flight not found)
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Error code and 0 for success response
example: IE23
message:
type: string
description: Contains the error message
example: "Flight(s) not found: Could not find all the flights required to make up this trip. Try changing dates, IATA codes, cabin class, etc."
search_criteria:
type: string
description: Contains the routes that failed to produce flights.
example: "[YYZ,YQS]"
500:
description: Server Error
/pre-booking/:
post:
summary: "Price Confirmation Report"
description: "When performing an availability or price confirmation request - when a user has selected their flights or is arriving on the site from
metasearch - please send a request to the following endpoint. This provides valuable data to our revenue management system in
determining markups for trips."
operationId: "PriceConfirmationReport"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PriceConfirmationReportRequest'
responses:
200:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: "success"
400:
description: Invalid Input
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: States whether request to book was successful.
example: Not booked
/booking/:
post:
summary: "Booking Report"
description: "When a booking is completed from a trip generated by Trip Ninja, report the booking to Trip Ninja via the booking endpoint."
operationId: "BookingReport"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BookingReportRequest'
responses:
200:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: "success"
400:
description: Invalid Input
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: States whether request to book was successful.
example: Not booked
/ticketing/:
post:
summary: "Ticketing Report"
description: |
When tickets are issued for a trip, please hit the following endpoint
operationId: "TicketingReport"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TicketingReportRequest'
responses:
200:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: "success"
400:
description: Invalid Input
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: States whether request to book was successful.
example: Not booked
/cancel/:
post:
summary: "Cancel Booking Report"
description: "To cancel a booking you have previously booked, report it to the Trip Ninja Service endpoint: “/cancel/”"
operationId: "CancelBookingReport"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CancelRequest'
responses:
200:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: "Trip has been cancelled."
400:
description: Invalid Input
content:
application/json:
schema:
type: object
properties:
response:
type: string
description: States whether request to cancel was successful.
example: Could not cancel trip, check your trip_id.
components:
schemas:
ItinerarySearchResponse:
title: Search Response
type: object
properties:
path_sequence:
type: array
description: An array of IATA codes representing the chronological order of your trip.
example: [ 'LON-CDG', 'CDG-YUL', 'YUL-LON' ]
currency:
type: string
description: Currency
example: CAD
itineraries:
$ref: '#/components/schemas/FSSearchItineraries'
ErrorDetails:
$ref: '#/components/schemas/ErrorDetails'
trip_id:
type: string
example: "a2cf0bdf2ecca12f8dbbc139af58c99a561f21a1"
description: A unique key used for identification and when booking a trip.
tn_net_fare_markup:
type: float
description: Markup specified by the Trip Ninja Net Fare to be applied at the itinerary level.
example: 25.0
SegmentSearchResponse:
title: Search Response
type: object
properties:
currency:
type: string
description: Currency
example: CAD
markup:
type: float
description: Markup specified by the Trip Ninja Net Fare to be applied at the itinerary level.
example: 25.0
path_sequence:
type: array
description: An array of IATA codes representing the chronological order of your trip.
example: ['LON-CDG', 'CDG-YUL', 'YUL-LON']
trip_id:
type: string
example: "a2cf0bdf2ecca12f8dbbc139af58c99a561f21a1"
description: A unique key used for identification and when booking a trip.
segments:
$ref: '#/components/schemas/TripOptions'
flight_details:
$ref: '#/components/schemas/FlightDetails'
ItineraryFSSearchResponse:
title: include_itineraries = true and route_flexible = false
type: object
properties:
fare_structure:
$ref: '#/components/schemas/ItinerarySearchResponse'
ItineraryFlexTripSearchResponse:
title: Itinerary FlexTrip Search Response
type: object
properties:
flex_trip:
$ref: '#/components/schemas/ItinerarySearchResponse'
SegmentFSSearchResponse:
title: include_itineraries = false and route_flexible = false
type: object
properties:
fare_structure:
$ref: '#/components/schemas/SegmentSearchResponse'
SegmentFlexTripSearchResponse:
title: Segment FlexTrip Search Response
type: object
properties:
flex_trip:
$ref: '#/components/schemas/SegmentSearchResponse'
SegmentFSSearchResponseWithFlexTrip:
title: include_itineraries = false and route_flexible = true
type: object
properties:
fare_structure:
$ref: '#/components/schemas/SegmentFSSearchResponse'
flex_trip:
$ref: '#/components/schemas/SegmentFlexTripSearchResponse'
ItineraryFsSerachResposneWithFlexTrip:
title: include_itineraries = true and route_flexible = true
type: object
properties:
fare_structure:
$ref: '#/components/schemas/ItineraryFSSearchResponse'
flex_trip:
$ref: '#/components/schemas/ItineraryFlexTripSearchResponse'
TripOptions:
title: Trip Options
type: array
items:
$ref: '#/components/schemas/SegmentOptions'
PriceBreakdownWithPassengerTypeCode:
type: array
description: Displays the pricing for each passenger type
items:
type: object
properties:
passenger_type_code:
type: string
example: "ADT"
base_price:
type: float
example: 73.00
total_price:
type: float
example: 132.39
taxes:
type: float
example: 59.39
tax_breakdown:
type: array
description: Breakdown of taxes amount into their categories
items:
type: object
properties:
category:
type: string
description: Category
example: "CA"
amount:
type: float
description: Amount of tax
example: 7.12
SegmentOptions:
title: Segment Options
type: array
items:
type: object
properties:
credential_info:
$ref: '#/components/schemas/CredentialInfo'
segment_id:
type: string
description: Segment ID
example: "0b736e4ff0d8b16bb5e83b9afe5204c0471d6e9b"
origin:
type: string
description: IATA code of the segment origin
example: LHR
origin_name:
type: string
description: Full name of the flight origin
example: "London, United Kingdom (LHR)"
destination:
type: string
description: IATA code of the segment destination
example: CDG
destination_name:
type: string
description: Full name of the flight destination
example: "Paris, France (CDG)"
itinerary_type:
type: string
enum: [ONE_WAY, OPEN_JAW, MULTI_PNR]
description: Type of the itinerary option.
example: ONE_WAY
itinerary_id:
type: string
description: Links part of the OPEN_JAW itineraries/VI-structures together which also make a PNR.
example: ad76ah7dhasd76asb76
itinerary_markup:
type: number
default: 0
description: Markup for the itinerary. Trip markup and Itinerary markup parameters are mutualy exclusive
example: 7
itinerary_structure:
type: String
description: |
"String representing the structure of the trip in terms of one-ways and open-jaw segments.
For example: [[0, 1], [3, 4], 2] means there would be three segments. One openjaw with key “01”,
one with key “34” and a one-way with key ‘2”."
See Price Confirm Report segment_ids field for more detail.
example: "[[0, 1], 2]"
literal_itinerary_structure:
type: Array of ints and/or Array of arrays
description: |
Array representing the structure of the trip in terms of one-ways and open-jaw segments.
For example: [[0, 1], [3, 4], 2] means there would be three segments. One openjaw with key “01”,
one with key “34” and a one-way with key ‘2”."
See Price Confirm Report segment_ids field for more detail.
example: [[0, 1], 2]
segment_position:
type: integer
description: Position of current segment in trip. Starts from 0.
example: 0
virtual_interline:
type: boolean
description: |
true if option is a vi solution
example: true
vi_solution_id:
type: string
description: ID mapping VI parts of the option together. Helps finding VI solutions located in same segment position.
example: fc906f39e5151f1bc5ef788b85f3d280770b5b7c__b9ebd56ff7bf07a65a3e4dc70e9551e4ae50f1da
nullable: true
risk_profile:
type: float
description: The probability of missing the connection and not performing the self-transfer during the VI self-connection (only returned if you have our average delay time module enabled, and only for VI segments with a self transfer)
example: 8.42
nullable: true
vi_segment_base_price:
type: float
description: The base price of the VI PNR not including taxes and fees.
example: 106.40
nullable: true
vi_segment_taxes:
type: float
description: The taxes associated with this VI PNR.
example: 24.12
nullable: true
vi_segment_fees:
type: float
description: The fees associated with this individual VI PNR.
example: 14.56
nullable: true
itinerary_index:
type: int
description: |
Position of the virtual interlining option in itinerary(PNR). Starts from 0
example: 0
nullable: true
vi_position:
type: integer
description: |
Position of the virtual interlining option in itinerary. Starts from 0
example: 1
nullable: true
weight:
type: float
description: Weight of the itinerary (time-value considered).
example: 239
price:
type: float
description: Price of the itinerary (fare and tax included).
example: 197.1
base_price:
type: float
description: Base price of the itinerary (tax excluded)
example: 0
taxes:
type: float
description: Tax price of the itinerary
example: 119.1
fees:
type: float
description: Fees for the itinerary
example: 0
transportation_time:
type: integer
description: Total transportation time for the itinerary
example: 425
fare_type:
type: string
description: Fare Type of the segment
example: Published
baggage:
type: object
description: Contains baggage information.
properties:
number_of_pieces:
type: integer
description: Number of bags allowed.
example: 0
additional_details:
type: object
description: Additional Details
properties:
e_ticketability:
type: boolean
example: true
latest_ticketing_time:
type: string
format: date
example: "11JUN20"
refundable:
type: boolean
example: true
cancel_penalty:
type: object
description: Information about cancellation
properties:
amount:
type: float
description: Cancellation penalty amount
example: 0
percentage:
type: float
description: Cancellation penalty percentage
example: 100
change_penalty:
type: object
description: Information about changing.
properties:
amount:
type: float
description: Change penalty amount
example: 78
percentage:
type: float
description: Change penalty percentage
example: 0
fare_types_info:
type: string
example: WS3 - Published fare
cabin_class:
type: String
enum: [ECONOMY, PREMIUM_ECONOMY, BUSINESS, FIRST, PREMIUM_FIRST]
description: cabin class for the itinerary
example: Economic Standard
alliance:
description: Parameter toggles the preferred alliance for your query. If there are results containing flights from the given alliance, only flights from that alliance will be returned. Otherwise it will return flights from any alliance. *Travelport Only*
required: false
type: string
example: "*A"
plating_carrier:
type: string
description: Plating carrier for segment
example: "SK"
fare_info_ref:
type: string
description: Flight identifier required to make a Travelport fare rule request. *Travelport Only*
example: "ZNqWNiVqWDKAyf27CAAAAA=="
fare_basis_code:
type: string
description: Fare Basis Code for the segment.
example: "OEOGHT"
fare_rule_key:
type: string
description: Key corresponding to above fare_info_ref also required to make a Travelport fare rule request. *Travelport Only*
example: "gws-eJxNjrEOwyAMRD8mut2mQFaokyZSVRiaDln6/5/RAxSpluw7eGA7peTE3SRKTP8x4Tu9nygfAwoc85WpwQcoDydENKCuddsPjA5OCEqHQ7U/W6I5CkxtHqgFzl4fVsmk96Uq2lw0yx+4zLrTlrwc9Z43Ee+VlwPJDK75AwvZKug="
private_fare:
type: boolean
description: True if segment is a private fare, otherwise False *Travelport customers only*
example: false
priced_passengers:
type: array
example: ['ADT','INF']
priced_passengers_standard_code:
type: array
example: ['ADT','INF']
price_breakdown_with_passenger_type_code:
$ref: '#/components/schemas/PriceBreakdownWithPassengerTypeCode'
segment_time_w_connections:
type: float
description: segment travel time accounting for time between flights
example: 75.0
flights:
type: array
description: flights information
items:
type: object
description: flight information
properties:
flight_detail_ref:
type: integer
description: reference to flight info in flight_details
example: 1
booking_code:
type: string
minLength: 1
maxLength: 1
example: B
fare_type:
type: string
example: Published fare
cabin_class:
type: string
example: Economic Standard
brands:
type: array
description: list of branded fares for the current segment
source:
type: string
description: Data source of the segment
example: "travelport"
travel_mode:
type: string
description: Travel mode of the segment (air, ground, etc.)
example: "air"
availability_source:
type: string
example: "S"
FlightDetails:
title: Flight Details
type: array
items:
type: object
properties:
origin:
type: string
description: IATA code of the segment origin
example: "LHR"
origin_name:
type: string
description: Full name of the flight origin
example: "London, United Kingdom (LHR)"
destination:
type: string
description: IATA code of the segment destination
example: "CDG"
destination_name:
type: string
description: Full name of the flight destination
example: "Paris, France (CDG)"
departure_time:
type: string
format: date-time
description: "Departure date and time with timezone."
# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webjet/refs/heads/main/openapi/webjet-tripninja-flights-core-openapi.yml