Back to top

Travatar Integration API

v1.0.0

Purpose

Travatar is an easy-to-integrate API that can be seamlessly connected to any application. By adding new dimensions to online flight searches, providing relevant information and introducing a new platform for traveler reviews, Travatar helps you book the best seat and makes it easier to compare the value of each flight. Designed to define the maximum comfortable seating it uses the traveler’s size, such as height and build, along with other preferences to provide the best available flight options for every destination. Based on personal preferences, Travatar provides the most relevant information on available flights. The API analyzes routes, previous trips and travelers’ reviews, so with every future journey your search for the most comfortable flight becomes even more accurate.

Authorization

Every request should contain an API key header. Mostly UUID4 key.

X-API-Key: 0bb6908e-9c0b-48c7-bcf7-5179be255f00

Comfort

Request data structure

  • Comfort request parts:
Name Req. Description
flights + An array of flights you want to measure a comfort for.
emails ± A list of existed Travatar customers.
anon ± A list of short-described anonymous customers.
type ± A global cabin type. Used when missed in a particular flight description.
  • A brief explanation of these parts:

1. Flights

You can use _ character for missed values or to mark flight as a wrapper.

To describe a flight properly you have to provide either equip or src, dst, dep values. You have to generate an identifier (mostly UUID4) for each flight by yourself.

Name Req. Type Description
air + string Airlines IATA code.
uuid + string Unique identifier for a flight. Not required for a wrapper.
sc ± string Particular seat class for a given airlines. Club World London City for British Airways, for example.
st ± string Define a cabin type to override global for a request.
dst ± string IATA code for an arrival airport.
src ± string IATA code for a departure airport.
dep ± date Departure date in (yyyy-MM-dd) format.
flight ± string Flight number.
equip ± string IATA code of an aircraft for a given flight.
flights ± array Array of flight descriptions for non-direct flights.

2. Emails

A list of emails of already registered Travatar customers.

{"emails": ["john@doe.com", "john@smith.com"]}

3. Anonymous

Each anonymous customer should have an unique identifier.

Name Req. Type Description
g + string A gender. Possible values [m, f]
h + int Customer height in centimeters.
s + string T-Shirt size. Possible values [XS, S, M, L, XL, XXL]
{
  "b7b97480-189d-4120-bb18-4304fea4343e": {
    "g": "m",
    "h": "183",
    "s": "L"
  }
}

4. Cabin type

Define global cabin class for a whole request.

Response data structure

  1. 2c9d8ff8-ad19-43b6-8e67-7411506b8fbb — Flight unique identifier.

  2. b7b97480-189d-4120-bb18-4304fea4343e — Anonymous customer unique identifier.

  3. john@doe.com — An email of a registered customer.

  4. lFit — A space between knees and next seat in meters.

  5. sFit — A free space for shoulders in meters.

  6. cl — A normalized score for legs. 0.0 — worst, 1.0 — best

  7. csh — The same for shoulders.

You will get lFit = 0 and sFit = 0 if we do not have any data about an aircraft or we can identify the aircraft model on a given route.

Comfort

Measure comfort
POST/integration/v1/comfort

Measure a comfort for a list of flights for given customers.

Example URI

POST https://api.b2b.travatar.com/integration/v1/comfort
Request
HideShow
Headers
Content-Type: application/json
X-API-Key: {YOUR_API_KEY}
Body
{
  "emails": [
    "john@doe.com",
    "john@smith.com"
  ],
  "anon": {
    "b7b97480-189d-4120-bb18-4304fea4343e": {
      "g": "m",
      "h": "183",
      "s": "L"
    }
  },
  "type": "Economy",
  "flights": [
    {
      "air": "_",
      "uuid": "d1963a4c-1ef2-4af0-b6a4-01b3bbf502de",
      "flights": [
        {
          "uuid": "d1963a4c-1ef2-4af0-b6a4-01b3bbf502ce",
          "air": "PS",
          "sc": "_",
          "st": "PremiumEconomy",
          "dst": "KBP",
          "src": "JFK",
          "dep": "2017-03-16",
          "flight": "232",
          "dur": 590,
          "equip": "733"
        },
        {
          "uuid": "448de46e-6af7-4641-8845-de5ae4db6ae0",
          "air": "PS",
          "sc": "_",
          "st": "PremiumEconomy",
          "dst": "CDG",
          "src": "KBP",
          "dep": "2017-03-16",
          "flight": "129",
          "dur": 210,
          "equip": "733"
        }
      ]
    },
    {
      "uuid": "4_2",
      "dep": "2016-11-23",
      "air": "BA",
      "src": "LGW",
      "dst": "JFK",
      "flight": "2273",
      "sc": "club world",
      "duc": 465
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/schema#",
  "definitions": {
    "flight": {
      "type": "object",
      "properties": {
        "air": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        "uuid": {
          "type": "string"
        },
        "sc": {
          "type": "string"
        },
        "st": {
          "type": "string"
        },
        "dst": {
          "type": "string"
        },
        "src": {
          "type": "string"
        },
        "dep": {
          "type": "string"
        },
        "flight": {
          "type": "string"
        },
        "equip": {
          "type": "string"
        },
        "dur": {
          "type": "number"
        },
        "flights": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "#/definitions/flight"
              }
            ]
          }
        }
      },
      "additionalProperties": false,
      "allOf": [
        {
          "anyOf": [
            {
              "required": [
                "equip"
              ]
            },
            {
              "required": [
                "flights"
              ]
            },
            {
              "required": [
                "src",
                "dst",
                "dep",
                "flight"
              ]
            }
          ]
        },
        {
          "required": [
            "air",
            "uuid"
          ]
        }
      ]
    },
    "anon": {
      "type": "object",
      "properties": {
        "g": {
          "type": "string",
          "enum": [
            "m",
            "f"
          ]
        },
        "h": {
          "type": "number",
          "minimum": 130,
          "maximum": 230
        },
        "s": {
          "type": "string",
          "enum": [
            "XS",
            "S",
            "M",
            "L",
            "XL"
          ]
        }
      },
      "required": [
        "g",
        "h",
        "s"
      ],
      "additionalProperties": false
    }
  },
  "type": "object",
  "properties": {
    "emails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    },
    "anon": {
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "allOf": [
            {
              "$ref": "#/definitions/anon"
            }
          ]
        }
      }
    },
    "flights": {
      "type": "array",
      "items": {
        "allOf": [
          {
            "$ref": "#/definitions/flight"
          }
        ]
      }
    },
    "type": {
      "type": "string",
      "enum": [
        "ECONOMY",
        "PREMIUM_ECONOMY",
        "BUSINESS",
        "FIRST"
      ]
    }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "required": [
        "flights"
      ]
    },
    {
      "anyOf": [
        {
          "required": [
            "emails"
          ]
        },
        {
          "required": [
            "anon"
          ]
        }
      ]
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "uuid": {
    "2c9d8ff8-ad19-43b6-8e67-7411506b8fbb": {
      "b7b97480-189d-4120-bb18-4304fea4343e": {
        "cl": 0.38,
        "csh": 0.37,
        "lFit": 0.06,
        "sFit": -0.09
      },
      "john@doe.com": {
        "cl": 0.38,
        "csh": 0.33,
        "lFit": 0.06,
        "sFit": -0.1
      },
      "john@smith.com": {
        "cl": 0.2,
        "csh": 0.07,
        "lFit": -0.04,
        "sFit": -0.18
      }
    },
    "448de46e-6af7-4641-8845-de5ae4db6ae0": {
      "b7b97480-189d-4120-bb18-4304fea4343e": {
        "cl": 0.38,
        "csh": 0.37,
        "lFit": 0.05,
        "sFit": -0.08
      },
      "john@doe.com": {
        "cl": 0.38,
        "csh": 0.33,
        "lFit": 0.05,
        "sFit": -0.1
      },
      "john@smith.com": {
        "cl": 0.2,
        "csh": 0.07,
        "lFit": -0.05,
        "sFit": -0.18
      }
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "code": 10001,
  "message": "Invalid Request",
  "fieldErrors": [
    {
      "field": "anonymous[b7b97480-189d-4120-bb18-4304fea4343e].height",
      "message": "Customer height should not be empty"
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "code": 40002,
  "message": "Arrival airport is not defined for a flight [Flight(price=null, flights=[], uuid=448de46e-6af7-4641-8845-de5ae4db6ae0, equip=null, seatClass=null, seatType=ECONOMY, dep=null, air=PS, src=null, dst=null, flight=null, duration=210)]"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "code": 40000,
  "message": "Request body is empty or malformed."
}
Response  415
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Method [PATCH] is not supported for given route. Please use [POST] method."
}

Optimal

Request data structure

  • Optimal request parts:
Name Req. Description
results + An array of results you’ve got from a comfort response + additional info.
emails ± A list of existed Travatar customers.
anon ± A list of short-described anonymous customers.
  • Lets explain these parts shortly:

1. Results

Name Req. Type Description
uuid + string Unique identifier for a flight.
prc + double A price for a flight.
lFit + double A space between knees and next seat in meters.
sFit + double A free space for shoulders in meters.
dur + int Flight duration in minutes.
results ± array Array of comfort results for non-direct flights.

2. Emails

A list of emails of already registered Travatar customers.

{"emails": ["john@doe.com", "john@smith.com"]}

3. Anonymous

Each anonymous customer should have an UUID4 identifier.

Name Req. Type Description
g + string A gender. Possible values [m, f]
h + int Customer height in centimeters.
s + string T-Shirt size. Possible values [XS, S, M, L, XL, XXL]
p + double Price preferences 0.0 -> 1.0. 0.0 — cheapest flights, 1.0 — more comfortable flights.
{
  "b7b97480-189d-4120-bb18-4304fea4343e": {
    "g": "m",
    "h": "183",
    "s": "L",
    "p": 0.12
  }
}

Response data structure

  1. 0fec77cb-e5cd-4c58-bffd-07d25c6f1c83 — Anonymous customer unique identifier

  2. a1 — Flight identifier.

  3. list — Ordered list of results.

  4. optimal — Identifier of the optimal flight.

  5. trash — Special list of flight with less comfort and less comfort.

  6. percentPrice — Difference with the optimal in price (in percents).

  7. percentComfort — Difference with the optimal in comfort (in percents).

Optimal

Calculate optimal
POST/integration/v1/optimal

Calculate the optimal flight accordingly to your preferences.

Example URI

POST https://api.b2b.travatar.com/integration/v1/optimal
Request
HideShow
Headers
Content-Type: application/json
X-API-Key: {YOUR_API_KEY}
Body
{
  "results": {
    "0fec77cb-e5cd-4c58-bffd-07d25c6f1c83": [
      {
        "uuid": "a1",
        "prc": 431,
        "sFit": -0.38,
        "lFit": -0.29,
        "dur": 180
      },
      {
        "uuid": "a2",
        "prc": 439,
        "sFit": -0.38,
        "lFit": -0.29,
        "dur": 186
      },
      {
        "uuid": "a3",
        "prc": 433.67,
        "results": {
          "a30": {
            "sFit": -0.29,
            "lFit": -0.19,
            "dur": 280
          },
          "a31": {
            "sFit": -0.24,
            "lFit": -0.13,
            "dur": 250
          }
        }
      }
    ]
  },
  "anon": {
    "0fec77cb-e5cd-4c58-bffd-07d25c6f1c83": {
      "g": "m",
      "h": 170,
      "s": "s"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/schema#",
  "definitions": {
    "result": {
      "type": "object",
      "properties": {
        "sFit": {
          "type": "number"
        },
        "lFit": {
          "type": "number"
        },
        "dur": {
          "type": "number",
          "minimum": 0,
          "maximum": 1440
        },
        "results": {
          "type": "object",
          "patternProperties": {
            "^.*$": {
              "allOf": [
                {
                  "$ref": "#/definitions/result"
                }
              ]
            }
          }
        },
        "uuid": {
          "type": "string"
        },
        "prc": {
          "type": "number"
        }
      },
      "additionalProperties": false
    },
    "anon": {
      "type": "object",
      "properties": {
        "g": {
          "type": "string",
          "enum": [
            "m",
            "f"
          ]
        },
        "h": {
          "type": "number",
          "minimum": 130,
          "maximum": 230
        },
        "s": {
          "type": "string",
          "enum": [
            "XS",
            "S",
            "M",
            "L",
            "XL"
          ]
        },
        "p": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "g",
        "h",
        "s",
        "p"
      ],
      "additionalProperties": false
    }
  },
  "type": "object",
  "properties": {
    "emails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    },
    "anon": {
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "allOf": [
            {
              "$ref": "#/definitions/anon"
            }
          ]
        }
      }
    },
    "results": {
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "#/definitions/result"
              }
            ]
          }
        }
      }
    }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "required": [
        "results"
      ]
    },
    {
      "anyOf": [
        {
          "required": [
            "emails"
          ]
        },
        {
          "required": [
            "anon"
          ]
        }
      ]
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "map": {
    "0fec77cb-e5cd-4c58-bffd-07d25c6f1c83": {
      "list": [
        {
          "uuid": "a1",
          "percentPrice": -0.01,
          "percentComfort": -1
        },
        {
          "uuid": "a3",
          "percentPrice": 0,
          "percentComfort": 0
        }
      ],
      "optimal": "a3",
      "trash": [
        {
          "uuid": "a2",
          "percentPrice": 0.01,
          "percentComfort": -1
        }
      ]
    }
  }
}

Generated by aglio on 10 May 2017