AIR API

Getting started

Booking engine API for flights. Search and book flights for every destination in world.

Main API URL

https://air.tmc-solutions.xyz

Versions

Curent available versions with endpoints:

v1

List
https://air.tmc-solutions.xyz/v1/list/
List
https://air.tmc-solutions.xyz/v1/choose/
Book
https://air.tmc-solutions.xyz/v1/book/

Key

Key is required for every API call.

Add key as GET param

https://air.tmc-solutions.xyz/v1/list/key=yourkey

List

List endpoint return list of flights combinations for requested origin, destination, departure, return.

List endpoint

https://air.tmc-solutions.xyz/v1/list?key=yourkey

Request

Request must be POST on List endpoint with required fields below

Required fields

adt
number of adult passengers - string/number
yth
number of youth passengers - string/number
chd
number of youth passengers - string/number
inf
number of infant passengers - string/number
search
origin, destination, departure - array
- origin
  3 code of origin - string
- destination
  3 code of destination - string
- deparure
  3 code of destination - string/date ( format: YYYY-MM-DD )

Oneway

{
   "adt":"1",
   "yth":0,
   "chd":0,
   "inf":0
   "search":[
      {
         "origin":"FRA",
         "destination":"LON",
         "departure":"2019-12-27"
      }
   ],
}

Return

{
   "adt":"1",
   "yth":0,
   "chd":0,
   "inf":0
   "search":[
      {
         "origin":"FRA",
         "destination":"LON",
         "departure":"2019-10-27"
      },
      {
         "origin":"LON",
         "destination":"FRA",
         "departure":"2019-11-04"
      }
   ]
}

Optional fields

limit
limit list options - string/number
offset
skip options - string/number
sort
sort options - array
- key
  flight field from list
- value
  ASC || DESC
filters
filter options - array
- key
  flight field from list
- value
  string
filtersRange
filter options - array
- key
  flight field from list
  - [min]
    string/number
  - [max]
    string/number

{
   "adt":"1",
   "yth":0,
   "chd":0,
   "inf":0,
   "limit":10,
   "offset":10,
   "sort":[
      "adtPrice":"DESC"
    ],
    "filters":[
       "carrier":"OU"
     ],
     "filtersRange":[
        "duration":[
          "min": "100",
          "max": "400",
        ]
      ],
   "search":[
      {
         "origin":"FRA",
         "destination":"LON",
         "departure":"2019-10-27"
      },
      {
         "origin":"LON",
         "destination":"FRA",
         "departure":"2019-11-04"
      }
   ]
}

Response

List response contains:

requestID
required value for other choose and book request - string
adt
number of requested adult passengers - string/number
yth
number of requested youth passengers - string/number
chd
number of requested child passengers - string/number
inf
number of requested infant passengers - string/number
optionsCount
number options in list - integer/number
filters
sum of values in list by options, flights, segments - array
- options
  sum of values in options - array
  - prices
  - carriers
- flights
  sum of values in flights - array
  - fareType
  - cabinClass
  - origin
  - destination
  - routing
  - duration
  - baggage
- segments
  - operatingCarriers
  - equipment
  - meals
  - tehnicalStops
options
combination of flights options - array
- requestID
  required value for other choose and book request - string
- optionID
  required value for other choose - string
- carriers
  validating carrier - string
- prices
  detailed list of prices for ADT,YTH,CHD and INF - array
  - fare
    option fare price - integer
  - tax
    option tax price - integer
  - total
    option total price - integer
- adtPrice
  option total price for ADT - integer
- ythPrice
  option total price for YTH - integer
- chdPrice
  option total price for CHD - integer
- infPrice
  option total price for INF - integer
- currency
  option prices currency - string
- flights
  list of flights for option - array
  - outgoing || incoming
    list of flights for option - array
    - flightID
      required value for other choose - string
    - fareType - string
    - bookingClass - string
    - cabinClass - string
    - validatingCarrier - string
    - ticketingTimeLimit - string/date
    - origin - string
    - originDetails
      origin details - array
      - code - string
      - icao - string
      - continentCode - string
      - countryCode - string
      - regionCode - string
      - cityCode - string
      - timeZone - string
      - UTC - string
      - latitude - float
      - longitude - float
      - elevation - integer
    - destination - string
    - destinationDetails
      destination details - array
      - code - string
      - icao - string
      - continentCode - string
      - countryCode - string
      - regionCode - string
      - cityCode - string
      - timeZone - string
      - UTC - string
      - latitude - float
      - longitude - float
      - elevation - integer
    - departure
      departure datetime - string/datetime
    - arrival
      arrival datetime - string/datetime
    - routing - string
    - duration
      flight duration in min - integer
    - seats
      available seats for flight - integer
    - segmentsNum
      number of segments - integer
    - segments
      list of segments for flight - array
      - operatingCarrier - string
      - airplaneCarrier - string
      - flightNumber - string
      - equipment - string
      - equipmentName - string
      - seats - string
      - meals - string
      - origin - string
      - originDetails
        origin details - array
        
        code - string
        
        icao - string
        
        continentCode - string
        
        countryCode - string
        
        regionCode - string
        
        cityCode - string
        
        timeZone - string
        
        UTC - string
        
        latitude - float
        
        longitude - float
        
        elevation - integer
      - destination - string
      - destinationDetails
        destination details - array
        
        code - string
        
        icao - string
        
        continentCode - string
        
        countryCode - string
        
        regionCode - string
        
        cityCode - string
        
        timeZone - string
        
        UTC - string
        
        latitude - float
        
        longitude - float
        
        elevation - integer
      - departure
        departure datetime - string/datetime
      - arrival
        arrival datetime - string/datetime
      - duration
        segment duration in min - integer
      - technicalStop
        number of tehnical stop for segment - string/number

Response example

{
   "requestID": "iOpqut3IUu9qSTazNXrU6zdAEI4aRrPm7mFNivEtbMv0L4de8z",
   "adt":"1",
   "yth":0,
   "chd":0,
   "inf":0
   "optionsCount":22,
   "filters":{...},
   "options":{...},
}

Filters example

{
   "filters":{
     "options":{
       "prices": {
          "2533": 1,
          "2869": 1,
          "3042": 1,
          ...
        },
        "carriers": {
          "AF": 6,
          "LH": 15,
          ...
        }
     },
     "flights":{...},
     "segments":{...},
   }
}

Options example

"options": [
    {
        "requestID": "iOpqut3IUu9qSTazNXrU6zdAEI4aRrPm7mFNivEtbMv0L4de8z",
        "optionID": "eXBzaWxvbi5hbWFkZXVzLjA=",
        "carriers": "TK"
        "prices": {
            "ADT": {
                "fare": 665,
                "tax": 1868,
                "total": 2533
            },
            "CHD": {
                "fare": 665,
                "tax": 1868,
                "total": 2533
            },
            "INF": {
                "fare": 665,
                "tax": 1868,
                "total": 2533
            },
            "YTH": {
                "fare": 665,
                "tax": 1868,
                "total": 2533
            }
        },
        "adtPrice": 2533,
        "ythPrice": 2533,
        "chdPrice": 2533,
        "infPrice": 2533,
        "currency": "HRK",
        "flights": [
          "outgoing":[...],
          "incoming":[...]
        ]
      },
      ...

Flights example

"incoming": [
    {
        "flightID": "b3V0Z29pbmcuUFVCLkxOMlhQQi5FLlRLLlpBRy4yMDE5LTAzLTE0IDIwOjAwLkJFWS4yMDE5LTAzLTE1IDAyOjM1LjI=",
        "type": "outgoing",
        "fareType": "PUB",
        "fareBase": "LN2XPB",
        "bookingClass": "L",
        "cabinClass": "E",
        "validatingCarrier": "TK",
        "ticketingTimeLimit": "2019-03-14",
        "origin": "ZAG",
        "originDetails": {
            "code": "ZAG",
            "icao": "LDZA",
            "continentCode": "EU",
            "countryCode": "HR",
            "regionCode": "",
            "cityCode": "ZAG",
            "timeZone": "Europe/Zagreb",
            "UTC": 1,
            "latitude": 45.733242,
            "longitude": 16.061519,
            "elevation": 353
        },
        "destination": "BEY",
        "destinationDetails": {
            "code": "BEY",
            "icao": "OLBA",
            "continentCode": "AS",
            "countryCode": "LB",
            "regionCode": "",
            "cityCode": "BEY",
            "timeZone": "Asia/Beirut",
            "UTC": 2,
            "latitude": 33.826073,
            "longitude": 35.493082,
            "elevation": 87
        },
        "departure": "2019-03-14 20:00",
        "arrival": "2019-03-15 02:35",
        "routing": "ZAG-IST-BEY",
        "routingCity": "",
        "routingCountry": "",
        "routingContinent": "",
        "duration": 395,
        "miles": "",
        "baggage": "",
        "seats": 9,
        "segmentsNum": 2,
        "segments": [...]
    },
    ...

Segments example

"segments": [
    {
        "operatingCarrier": "TK",
        "airplaneCarrier": "",
        "flightNumber": "1056",
        "equipment": "321",
        "equipmentName": "Airbus A321",
        "seats": 9,
        "meals": "",
        "origin": "ZAG",
        "originDetails": {
            "code": "ZAG",
            "icao": "LDZA",
            "continentCode": "EU",
            "countryCode": "HR",
            "regionCode": "",
            "cityCode": "ZAG",
            "timeZone": "Europe/Zagreb",
            "UTC": 1,
            "latitude": 45.733242,
            "longitude": 16.061519,
            "elevation": 353
        },
        "destination": "IST",
        "destinationDetails": {
            "code": "IST",
            "icao": "LTBA",
            "continentCode": "AS",
            "countryCode": "TR",
            "regionCode": "",
            "cityCode": "IST",
            "timeZone": "Europe/Istanbul",
            "UTC": 3,
            "latitude": 40.976667,
            "longitude": 28.815278,
            "elevation": 158
        },
        "departure": "2019-03-14 20:00",
        "arrival": "2019-03-15 00:10",
        "duration": 250,
        "miles": "",
        "baggage": "",
        "technicalStop": "0"
    },
    ...

Choose

Choose endpoint check and validate price&seat availability from list response

Choose endpoint

https://air.tmc-solutions.xyz/v1/choose?key=yourkey

Request

Request must be POST on Choose endpoint with required fields below

Required fields

requestID
given from list request - string
option
choosen option - string
flights
choosen flights for option - array
- flightID - string
  3 code of origin - string

Oneway

{
   "requestID":"PG6dHkK4eaPHp4kenAitfGIKMDhSA95slJjh8eynsaAMsry4Gz",
   "option":"eXBzaWxvbi5hbWFkZXVzLjU=",
   "flights":[
      "b3V0Z29pbmcuUFVCLlgxQVJXSFI5LkUuQUYuWkFHLjIwMTktMDUtMTQgMTc6NTUuTEhSLjIwMTktMDUtMTUgMTk6MjAuMg=="
   ]
}

Return

{
   "requestID":"PG6dHkK4eaPHp4kenAitfGIKMDhSA95slJjh8eynsaAMsry4Gz",
   "option":"eXBzaWxvbi5hbWFkZXVzLjU=",
   "flights":[
      "b3V0Z29pbmcuUFVCLlgxQVJXSFI5LkUuQUYuWkFHLjIwMTktMDUtMTQgMTc6NTUuTEhSLjIwMTktMDUtMTUgMTk6MjAuMg==",
      "b3V0Z29pbmcuUFVCLlgxQVJXSFI5LkUuQUYuWkFjztewrerrdsfsadhasTc6NTUuTEhSLjIwMTktMDUtMTUgMTk6MjAuMg==",
   ]
}

Response

Choose response contains:

requestID
required value for book request - string
status
status of choosen option - string
priceDiff
if price changed contains difference between list price - array
additional
additional options for each passenger, baggage, priority boarding... - array
rule
fare rule for option - string/base64encoded
option
choosen option details - object
- requestID
  required value for other choose and book request - string
- optionID
  required value for other choose - string
- carriers
  list of validating carriers in flights - array/strings
- prices
  detailed list of prices for ADT,YTH,CHD and INF - array
  - fare
    option fare price - integer
  - tax
    option tax price - integer
  - total
    option total price - integer
- adtPrice
  option total price for ADT - integer
- ythPrice
  option total price for YTH - integer
- chdPrice
  option total price for CHD - integer
- infPrice
  option total price for INF - integer
- currency
  option prices currency - string
- flights
  list of flights for option - array
  - flightID
    required value for other choose - string
  - fareType - string
  - bookingClass - string
  - cabinClass - string
  - validatingCarrier - string
  - ticketingTimeLimit - string/date
  - origin - string
  - originDetails
    origin details - array
    - code - string
    - icao - string
    - continentCode - string
    - countryCode - string
    - regionCode - string
    - cityCode - string
    - timeZone - string
    - UTC - string
    - latitude - float
    - longitude - float
    - elevation - integer
  - destination - string
  - destinationDetails
    destination details - array
    - code - string
    - icao - string
    - continentCode - string
    - countryCode - string
    - regionCode - string
    - cityCode - string
    - timeZone - string
    - UTC - string
    - latitude - float
    - longitude - float
    - elevation - integer
  - departure
    departure datetime - string/datetime
  - arrival
    arrival datetime - string/datetime
  - routing - string
  - duration
    flight duration in min - integer
  - seats
    available seats for flight - integer
  - segmentsNum
    number of segments - integer
  - segments
    list of segments for flight - array
    - operatingCarrier - string
    - airplaneCarrier - string
    - carrier - string
    - flightNumber - string
    - equipment - string
    - equipmentName - string
    - seats - string
    - meals - string
    - origin - string
    - originDetails
      origin details - array
      - code - string
      - icao - string
      - continentCode - string
      - countryCode - string
      - regionCode - string
      - cityCode - string
      - timeZone - string
      - UTC - string
      - latitude - float
      - longitude - float
      - elevation - integer
    - destination - string
    - destinationDetails
      destination details - array
      - code - string
      - icao - string
      - continentCode - string
      - countryCode - string
      - regionCode - string
      - cityCode - string
      - timeZone - string
      - UTC - string
      - latitude - float
      - longitude - float
      - elevation - integer
    - departure
      departure datetime - string/datetime
    - arrival
      arrival datetime - string/datetime
    - duration
      segment duration in min - integer
    - technicalStop
      number of tehnical stop for segment - string/number

Response example

{
   "requestID": "iOpqut3IUu9qSTazNXrU6zdAEI4aRrPm7mFNivEtbMv0L4de8z",
   "status":"success",
   "option":{...},
   "priceDiff": null,
   "additional":"",
   "rule": "IyMjIyMjIyMjIyMjIyMjI.....",
}

Option example

"option": {
  "requestID": "iOpqut3IUu9qSTazNXrU6zdAEI4aRrPm7mFNivEtbMv0L4de8z",
  "optionID": "eXBzaWxvbi5hbWFkZXVzLjA=",
  "carriers": [
      "TK"
  ],
  "prices": {
      "ADT": {
          "fare": 665,
          "tax": 1868,
          "total": 2533
      },
      "CHD": {
          "fare": 665,
          "tax": 1868,
          "total": 2533
      },
      "INF": {
          "fare": 665,
          "tax": 1868,
          "total": 2533
      },
      "YTH": {
          "fare": 665,
          "tax": 1868,
          "total": 2533
      }
  },
  "adtPrice": 2533,
  "ythPrice": 2533,
  "chdPrice": 2533,
  "infPrice": 2533,
  "currency": "HRK",
  "flights": [
    "incoming":[...],
    "outgoing":[...]
  ]
}

Flights example

  "incoming": [
      {
          "flightID": "b3V0Z29pbmcuUFVCLkxOMlhQQi5FLlRLLlpBRy4yMDE5LTAzLTE0IDIwOjAwLkJFWS4yMDE5LTAzLTE1IDAyOjM1LjI=",
          "type": "outgoing",
          "fareType": "PUB",
          "fareBase": "LN2XPB",
          "bookingClass": "L",
          "cabinClass": "E",
          "validatingCarrier": "TK",
          "ticketingTimeLimit": "2019-03-14",
          "origin": "ZAG",
          "originDetails": {
              "code": "ZAG",
              "icao": "LDZA",
              "continentCode": "EU",
              "countryCode": "HR",
              "regionCode": "",
              "cityCode": "ZAG",
              "timeZone": "Europe/Zagreb",
              "UTC": 1,
              "latitude": 45.733242,
              "longitude": 16.061519,
              "elevation": 353
          },
          "destination": "BEY",
          "destinationDetails": {
              "code": "BEY",
              "icao": "OLBA",
              "continentCode": "AS",
              "countryCode": "LB",
              "regionCode": "",
              "cityCode": "BEY",
              "timeZone": "Asia/Beirut",
              "UTC": 2,
              "latitude": 33.826073,
              "longitude": 35.493082,
              "elevation": 87
          },
          "departure": "2019-03-14 20:00",
          "arrival": "2019-03-15 02:35",
          "routing": "ZAG-IST-BEY",
          "routingCity": "",
          "routingCountry": "",
          "routingContinent": "",
          "duration": 395,
          "miles": "",
          "baggage": "",
          "seats": 9,
          "segmentsNum": 2,
          "segments": [...]
      },
      ...

Segments example

  "segments": [
      {
          "operatingCarrier": "TK",
          "airplaneCarrier": "",
          "flightNumber": "1056",
          "equipment": "321",
          "equipmentName": "Airbus A321",
          "seats": 9,
          "meals": "",
          "origin": "ZAG",
          "originDetails": {
              "code": "ZAG",
              "icao": "LDZA",
              "continentCode": "EU",
              "countryCode": "HR",
              "regionCode": "",
              "cityCode": "ZAG",
              "timeZone": "Europe/Zagreb",
              "UTC": 1,
              "latitude": 45.733242,
              "longitude": 16.061519,
              "elevation": 353
          },
          "destination": "IST",
          "destinationDetails": {
              "code": "IST",
              "icao": "LTBA",
              "continentCode": "AS",
              "countryCode": "TR",
              "regionCode": "",
              "cityCode": "IST",
              "timeZone": "Europe/Istanbul",
              "UTC": 3,
              "latitude": 40.976667,
              "longitude": 28.815278,
              "elevation": 158
          },
          "departure": "2019-03-14 20:00",
          "arrival": "2019-03-15 00:10",
          "duration": 250,
          "miles": "",
          "baggage": "",
          "technicalStop": "0"
      },
      ...

Book

Book endpoint generate booking and reserve sets in choose option flights

Book endpoint

https://air.tmc-solutions.xyz/v1/book?key=yourkey

Request

Request must be POST on Book endpoint with required fields below

Required fields

requestID
given from choose request - string
payment
payment type - string
- invoice
- cash
customer
customer - object
- firstName - string
- lastName - string
- phone - string
- email - string
passanger
passanger - array
- firstName - string
- lastName - string
- birthDate - string * required for CHD or INF

Request example

{
   "requestID":"PG6dHkK4eaPHp4kenAitfGIKMDhSA95slJjh8eynsaAMsry4Gz",
   "payment":"invoice",
   "customer":{
     "firstName":"Foo",
     "lastName":"Bar",
     "phone":"+003443032432",
     "email":"foo@bar.com",
   }
   "passegers":[
    {
	"type":"ADT"
	"firstName":"Foo",
	"lastName":"Bar",
	"birthDate":"1980-01-01"
    },
    ...
   ]
}

Response

Book response contains:

requestID
required value for book request - string
recordLocator
booking code - string
ticketingLimit
booking expiry datetime - string
status
status of choosen option - string
payment
requested payment - string
customer
requested customer details - object
passengers
requested passengers details - array
rule
fare rule for option - string/base64encoded
option
choosen option details - object
- requestID
  required value for other choose and book request - string
- optionID
  required value for other choose - string
- carriers
  list of validating carriers in flights - array/strings
- prices
  detailed list of prices for ADT,YTH,CHD and INF - array
  - fare
    option fare price - integer
  - tax
    option tax price - integer
  - total
    option total price - integer
- adtPrice
  option total price for ADT - integer
- ythPrice
  option total price for YTH - integer
- chdPrice
  option total price for CHD - integer
- infPrice
  option total price for INF - integer
- currency
  option prices currency - string
- flights
  list of flights for option - array
  - flightID
    required value for other choose - string
  - fareType - string
  - bookingClass - string
  - cabinClass - string
  - validatingCarrier - string
  - ticketingTimeLimit - string/date
  - origin - string
  - originDetails
    origin details - array
    - code - string
    - icao - string
    - continentCode - string
    - countryCode - string
    - regionCode - string
    - cityCode - string
    - timeZone - string
    - UTC - string
    - latitude - float
    - longitude - float
    - elevation - integer
  - destination - string
  - destinationDetails
    destination details - array
    - code - string
    - icao - string
    - continentCode - string
    - countryCode - string
    - regionCode - string
    - cityCode - string
    - timeZone - string
    - UTC - string
    - latitude - float
    - longitude - float
    - elevation - integer
  - departure
    departure datetime - string/datetime
  - arrival
    arrival datetime - string/datetime
  - routing - string
  - duration
    flight duration in min - integer
  - seats
    available seats for flight - integer
  - segmentsNum
    number of segments - integer
  - segments
    list of segments for flight - array
    - operatingCarrier - string
    - airplaneCarrier - string
    - flightNumber - string
    - equipment - string
    - equipmentName - string
    - seats - string
    - meals - string
    - origin - string
    - originDetails
      origin details - array
      - code - string
      - icao - string
      - continentCode - string
      - countryCode - string
      - regionCode - string
      - cityCode - string
      - timeZone - string
      - UTC - string
      - latitude - float
      - longitude - float
      - elevation - integer
    - destination - string
    - destinationDetails
      destination details - array
      - code - string
      - icao - string
      - continentCode - string
      - countryCode - string
      - regionCode - string
      - cityCode - string
      - timeZone - string
      - UTC - string
      - latitude - float
      - longitude - float
      - elevation - integer
    - departure
      departure datetime - string/datetime
    - arrival
      arrival datetime - string/datetime
    - duration
      segment duration in min - integer
    - technicalStop
      number of tehnical stop for segment - string/number

Response example

{
    "requestID": "cX2cPXKxiZdy0ktJT2EuG2HYi9Cif16d8jIDPtPDenTY6l20Z0",
    "adt": "1",
    "chd": "0",
    "yth": "0",
    "inf": "0",
    "customer": {
        "version": "",
        "firstName": "Foo",
        "lastName": "Bar",
        "gender": "",
        "birthDate": "",
        "phone": "+2312434434343",
        "email": "foo@bar.com",
        "country": "",
        "city": "",
        "zipcode": "",
        "street": "",
        "streetNo": ""
    },
    "passangers": [
        {
            "type": "",
            "firstName": "Foo",
            "lastName": "Bar",
            "gender": "",
            "birthDate": ""
        }
    ],
    "payment": "invoice",
    "recordLocator": "45DFHS",
    "status": "success",
    "ticketingLimit": "2019-02-18 23:59",
    "option": {
      ...
    }
    "rule": "...."
}