Flight API Specification¶
Overview¶
The Flight API provides endpoints for searching flights, fetching results, and pricing flight offers.
Base Path: /flight
Content Types:
- Request: application/json
- Response: application/json
Response Format¶
All endpoints return a TlinqApiResponse object:
Date Format: All dates are returned in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss)
Endpoints¶
POST /flight/getLocations¶
Searches for airport/city locations for autocomplete.
Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | keyword | string | Yes | Location search keyword (city/airport name or code) |
Request Example:
Response Structure:
{
"apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
"apiData": [
{
"name": "Dubai International Airport",
"type": "location",
"subType": "AIRPORT",
"detailedName": "Dubai International Airport",
"iataCode": "DXB",
"cityName": "Dubai",
"cityCode": "DXB",
"countryName": "United Arab Emirates",
"countryCode": "AE",
"regionCode": "MENA"
},
{
"name": "Al Maktoum International Airport",
"type": "location",
"subType": "AIRPORT",
"detailedName": "Dubai World Central - Al Maktoum International",
"iataCode": "DWC",
"cityName": "Dubai",
"cityCode": "DXB",
"countryName": "United Arab Emirates",
"countryCode": "AE",
"regionCode": "MENA"
}
]
}
POST /flight/getAirlines¶
Searches for airlines by code.
Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | code | string | Yes | Airline code or partial code |
Request Example:
Response Structure:
{
"apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
"apiData": [
{
"iataCode": "EK",
"icaoCode": "UAE",
"businessName": "Emirates",
"commonName": "Emirates",
"type": "airline"
}
]
}
POST /flight/search¶
Initiates a flight search.
Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | origin | string | Yes | Origin IATA code | | destination | string | Yes | Destination IATA code | | departureDate | string | Yes | Departure date (yyyy-MM-dd) | | returnDate | string | No | Return date for round trips (yyyy-MM-dd) | | numAdults | integer | Yes | Number of adult passengers | | numChildren | integer | No | Number of children (default: 0) | | numInfants | integer | No | Number of infants (default: 0) | | sortOrder | integer | No | Sort order (default: 0 = price+duration) | | grouping | integer | No | Result grouping mode (0 = individual, 1 = grouped) |
Request Example (One-way):
{
"session": "user-session-token",
"origin": "DXB",
"destination": "LHR",
"departureDate": "2025-07-15",
"numAdults": 2,
"numChildren": 1,
"numInfants": 0,
"sortOrder": 0,
"grouping": 0
}
Request Example (Round-trip):
{
"session": "user-session-token",
"origin": "DXB",
"destination": "LHR",
"departureDate": "2025-07-15",
"returnDate": "2025-07-22",
"numAdults": 2,
"numChildren": 1,
"numInfants": 0
}
Response Structure (Individual Offers - grouping=0):
{
"apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
"apiData": {
"searchId": "SRCH-20250615-123456",
"pageId": 1,
"groupType": 0,
"totalRes": 150,
"offers": [
{
"id": "1",
"source": "AMADEUS",
"instantTicketingRequired": false,
"nonHomogenous": false,
"oneWay": true,
"lastTicketingDate": "2025-07-10",
"currency": "AED",
"totalAmount": 2850.00,
"baseAmount": 2500.00,
"grandTotal": 2850.00,
"itineraries": [
{
"duration": "PT7H15M",
"segments": [
{
"segmentId": "1",
"duration": "PT7H15M",
"carrierCode": "EK",
"carrierName": "Emirates",
"flightNumber": "5",
"numberOfStops": 0,
"blacklistedInEU": false,
"departureAirportCode": "DXB",
"departureAirportName": "Dubai International Airport",
"departureTerminal": "3",
"departureTime": "2025-07-15T08:00:00",
"arrivalAirportCode": "LHR",
"arrivalAirportName": "London Heathrow Airport",
"arrivalTerminal": "3",
"arrivalTime": "2025-07-15T12:15:00"
}
]
}
],
"paxPricing": [
{
"passengerId": "1",
"fareOption": "STANDARD",
"passengerType": "ADULT",
"currency": "AED",
"totalAmount": 950.00,
"baseAmount": 833.33,
"grandTotal": 950.00,
"segmentFares": null
},
{
"passengerId": "2",
"fareOption": "STANDARD",
"passengerType": "ADULT",
"currency": "AED",
"totalAmount": 950.00,
"baseAmount": 833.33,
"grandTotal": 950.00,
"segmentFares": null
},
{
"passengerId": "3",
"fareOption": "STANDARD",
"passengerType": "CHILD",
"currency": "AED",
"totalAmount": 950.00,
"baseAmount": 833.34,
"grandTotal": 950.00,
"segmentFares": null
}
]
},
{
"id": "2",
"source": "AMADEUS",
"instantTicketingRequired": false,
"oneWay": true,
"lastTicketingDate": "2025-07-10",
"currency": "AED",
"totalAmount": 2100.00,
"baseAmount": 1850.00,
"grandTotal": 2100.00,
"itineraries": [
{
"duration": "PT10H30M",
"segments": [
{
"segmentId": "1",
"duration": "PT2H45M",
"carrierCode": "QR",
"carrierName": "Qatar Airways",
"flightNumber": "1001",
"numberOfStops": 0,
"departureAirportCode": "DXB",
"departureAirportName": "Dubai International Airport",
"departureTerminal": "1",
"departureTime": "2025-07-15T06:00:00",
"arrivalAirportCode": "DOH",
"arrivalAirportName": "Hamad International Airport",
"arrivalTime": "2025-07-15T06:45:00"
},
{
"segmentId": "2",
"duration": "PT7H00M",
"carrierCode": "QR",
"carrierName": "Qatar Airways",
"flightNumber": "15",
"numberOfStops": 0,
"departureAirportCode": "DOH",
"departureAirportName": "Hamad International Airport",
"departureTime": "2025-07-15T08:30:00",
"arrivalAirportCode": "LHR",
"arrivalAirportName": "London Heathrow Airport",
"arrivalTerminal": "4",
"arrivalTime": "2025-07-15T13:30:00"
}
]
}
],
"paxPricing": [
{
"passengerId": "1",
"passengerType": "ADULT",
"currency": "AED",
"totalAmount": 700.00,
"baseAmount": 616.67,
"grandTotal": 700.00
}
]
}
],
"offerGroups": null
}
}
Sort Order Values: | Value | Description | |-------|-------------| | 0 | Price + Duration (default) | | 1 | Price only | | 2 | Duration only |
Grouping Values: | Value | Description | |-------|-------------| | 0 | No grouping (individual offers) | | 1 | Grouped by itinerary |
Error Codes:
- INVALID_FORMAT - Date format incorrect
POST /flight/fetchResults¶
Fetches paginated results from a previous search.
Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | searchId | string | Yes | Search ID from previous search | | page | integer | Yes | Page number to fetch | | grouping | string | No | "IND" for individual or "GRP" for grouped |
Request Example:
{
"session": "user-session-token",
"searchId": "SRCH-20250615-123456",
"page": 2,
"grouping": "IND"
}
Response Structure:
{
"apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
"apiData": {
"searchId": "SRCH-20250615-123456",
"pageId": 2,
"groupType": 0,
"totalRes": 150,
"offers": [
{
"id": "21",
"source": "AMADEUS",
"currency": "AED",
"totalAmount": 3200.00,
"itineraries": [
{
"duration": "PT8H30M",
"segments": [
{
"segmentId": "1",
"carrierCode": "BA",
"carrierName": "British Airways",
"flightNumber": "108",
"departureAirportCode": "DXB",
"departureTime": "2025-07-15T10:30:00",
"arrivalAirportCode": "LHR",
"arrivalTime": "2025-07-15T15:00:00"
}
]
}
]
}
],
"offerGroups": null
}
}
POST /flight/price¶
Gets detailed pricing for a specific flight offer.
Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | flightOfferId | string | Yes | Flight offer identifier | | passengers | array | No | Passenger details for pricing |
Request Example:
Response Structure:
{
"apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
"apiData": {
"id": "1",
"type": "flight-offer",
"source": "GDS",
"instantTicketingRequired": false,
"nonHomogenous": false,
"oneWay": true,
"disablePricing": false,
"lastTicketingDate": "2025-07-10",
"paymentCardRequired": false,
"lastTicketingDateTime": "2025-07-10T23:59:00Z",
"noOfBookableSeats": 9,
"itineraries": [
{
"duration": "PT7H15M",
"segments": [
{
"segmentId": "1",
"duration": "PT7H15M",
"carrierCode": "EK",
"carrierName": "Emirates",
"flightNumber": "5",
"numberOfStops": 0,
"blacklistedInEU": false,
"departureAirportCode": "DXB",
"departureAirportName": "Dubai International Airport",
"departureTerminal": "3",
"departureTime": "2025-07-15T08:00:00",
"arrivalAirportCode": "LHR",
"arrivalAirportName": "London Heathrow Airport",
"arrivalTerminal": "3",
"arrivalTime": "2025-07-15T12:15:00"
}
]
}
],
"price": {
"currency": "AED",
"base": "2500.00",
"total": "2850.00",
"grandTotal": "2850.00",
"refundableTaxes": "150.00",
"margin": null,
"billingCurrency": "AED",
"fees": [
{
"amount": "0.00",
"type": "SUPPLIER"
},
{
"amount": "0.00",
"type": "TICKETING"
}
],
"taxes": [
{
"amount": "100.00",
"code": "YQ"
},
{
"amount": "150.00",
"code": "GB"
},
{
"amount": "100.00",
"code": "UB"
}
],
"additionalServices": null
},
"pricingOptions": {
"fareType": ["PUBLISHED"],
"includedCheckedBagsOnly": true
},
"validatingAirlines": ["EK"],
"travelerPricings": [
{
"travelerId": "1",
"travelerType": "ADULT",
"fareOption": "STANDARD",
"associatedAdultId": null,
"price": {
"currency": "AED",
"base": "833.33",
"total": "950.00"
},
"fareDetailsBySegment": [
{
"segmentId": "1",
"cabin": "ECONOMY",
"fareBasis": "YOWAE",
"class": "Y",
"includedCheckedBags": {
"weight": 30,
"weightUnit": "KG"
},
"brandedFare": "ECONOMY FLEX",
"brandedFareLabel": "ECONOMY FLEX"
}
]
},
{
"travelerId": "2",
"travelerType": "ADULT",
"fareOption": "STANDARD",
"price": {
"currency": "AED",
"base": "833.33",
"total": "950.00"
},
"fareDetailsBySegment": [
{
"segmentId": "1",
"cabin": "ECONOMY",
"fareBasis": "YOWAE",
"class": "Y"
}
]
},
{
"travelerId": "3",
"travelerType": "CHILD",
"fareOption": "STANDARD",
"associatedAdultId": "1",
"price": {
"currency": "AED",
"base": "833.34",
"total": "950.00"
},
"fareDetailsBySegment": [
{
"segmentId": "1",
"cabin": "ECONOMY",
"fareBasis": "YOWAE/CH25",
"class": "Y"
}
]
}
]
}
}
Data Models¶
CFlightOfferSet¶
| Field | Type | Description |
|---|---|---|
| searchId | string | Search identifier for pagination |
| pageId | integer | Current page number |
| groupType | integer | 0 = individual, 1 = grouped |
| totalRes | integer | Total matching offers |
| offers | array | Array of CFlightOffer objects |
| offerGroups | array | Array of CFlightOfferGroup objects (when grouped) |
CFlightOffer¶
| Field | Type | Description |
|---|---|---|
| id | string | Unique offer identifier |
| source | string | Data source (e.g., "AMADEUS") |
| instantTicketingRequired | boolean | Immediate ticketing required |
| nonHomogenous | boolean | Mixed carriers |
| oneWay | boolean | One-way flight |
| lastTicketingDate | string | Last date to ticket |
| currency | string | Currency code |
| totalAmount | number | Total price |
| baseAmount | number | Base fare amount |
| grandTotal | number | Grand total including taxes |
| itineraries | array | Array of CItinerary objects |
| paxPricing | array | Array of CPassengerPricing objects |
CItinerary¶
| Field | Type | Description |
|---|---|---|
| duration | string | Total duration (ISO 8601, e.g., "PT7H15M") |
| segments | array | Array of CItinerarySegment objects |
CItinerarySegment¶
| Field | Type | Description |
|---|---|---|
| segmentId | string | Segment identifier |
| duration | string | Segment duration |
| carrierCode | string | Airline IATA code |
| carrierName | string | Airline name |
| flightNumber | string | Flight number |
| numberOfStops | integer | Number of stops |
| blacklistedInEU | boolean | Blacklisted in EU |
| departureAirportCode | string | Departure airport IATA code |
| departureAirportName | string | Departure airport name |
| departureTerminal | string | Departure terminal |
| departureTime | string | Departure datetime (ISO 8601) |
| arrivalAirportCode | string | Arrival airport IATA code |
| arrivalAirportName | string | Arrival airport name |
| arrivalTerminal | string | Arrival terminal |
| arrivalTime | string | Arrival datetime (ISO 8601) |
CPassengerPricing¶
| Field | Type | Description |
|---|---|---|
| passengerId | string | Passenger identifier |
| fareOption | string | Fare option selected |
| passengerType | string | ADULT, CHILD, or INFANT |
| currency | string | Currency code |
| totalAmount | number | Total for this passenger |
| baseAmount | number | Base fare |
| grandTotal | number | Grand total |
| segmentFares | array | Fare details per segment |
CPricedOffer¶
| Field | Type | Description |
|---|---|---|
| id | string | Offer identifier |
| type | string | Offer type |
| source | string | Data source |
| instantTicketingRequired | boolean | Immediate ticketing required |
| oneWay | boolean | One-way flight |
| disablePricing | boolean | Pricing disabled flag |
| lastTicketingDate | string | Last ticketing date |
| paymentCardRequired | boolean | Card payment required |
| lastTicketingDateTime | datetime | Last ticketing datetime |
| noOfBookableSeats | integer | Available seats |
| itineraries | array | Flight itineraries |
| price | CExtPrice | Detailed price breakdown |
| pricingOptions | object | Pricing options |
| validatingAirlines | array | Validating airline codes |
| travelerPricings | array | Price per traveler |
CExtPrice¶
| Field | Type | Description |
|---|---|---|
| currency | string | Currency code |
| base | string | Base fare amount |
| total | string | Total amount |
| grandTotal | string | Grand total |
| refundableTaxes | string | Refundable tax amount |
| margin | string | Margin amount |
| billingCurrency | string | Billing currency |
| fees | array | Array of fee objects |
| taxes | array | Array of tax objects |
| additionalServices | array | Additional service charges |
CTravelerPricing¶
| Field | Type | Description |
|---|---|---|
| travelerId | string | Traveler identifier |
| travelerType | string | ADULT, CHILD, HELD_INFANT, SEATED_INFANT |
| fareOption | string | Fare option |
| associatedAdultId | string | Associated adult (for infants) |
| price | CPrice | Price for this traveler |
| fareDetailsBySegment | array | Fare details per segment |
CLocation¶
| Field | Type | Description |
|---|---|---|
| name | string | Location name |
| type | string | Type (e.g., "location") |
| subType | string | Sub-type (AIRPORT, CITY) |
| detailedName | string | Detailed name |
| iataCode | string | IATA airport/city code |
| cityName | string | City name |
| cityCode | string | City IATA code |
| countryName | string | Country name |
| countryCode | string | Country ISO code |
| regionCode | string | Region code |
CAirline¶
| Field | Type | Description |
|---|---|---|
| iataCode | string | IATA airline code |
| icaoCode | string | ICAO airline code |
| businessName | string | Business/legal name |
| commonName | string | Common/marketing name |
| type | string | Type (airline) |