Guides

Using Reservations API

In this guide we are going to explain how to use Availability API and what data can you get from it.
Make sure you have your apikey - instructions on how to get it can be found here.

The API retrieves full availability for given route and time period. Let's have a look at its base URL:

http://fraas-prod.apigee.net/pub/v1/reservations/AvailabilityV2

Now let's explain what query parameters it has:

Parameter
Optional
Type
Description
Example
Origin no string(length=3) Origin station IATA code &Origin=DUB
Destination no string(length=3) Destination station IATA code &Destination=STN
DateOut no date >= than today Outbound Date &DateOut=2015-02-15
DateIn yes date >= than today Inbound Date &DateIn=2015-02-15
FlexDaysOut yes int (min=0, max=6) Flexible days after Outbound, counting from DateOut onwards &FlexDaysOut=6
FlexDaysBeforeOut yes int (min=0, max=6) Flexible days before Outbound, counting from DateOut backwards &FlexDaysBeforeOut=6
FlexDaysIn yes int (min=0, max=6) Flexible days for Inbound, counting from DateIn onwards

&FlexDaysIn=6

FlexDaysBeforeIn yes int (min=0, max=6) Flexible days before Inbound, counting from DateIn backwards &FlexDaysBeforeIn=6
RoundTrip yes, defaults to false boolean Is roundtrip?  &RoundTrip=True
ADT yes, defaults to 1 int Number of Adults  &ADT=2
TEEN yes, defaults to 0 int Number of Teens  &TEEN=2
CHD yes, defaults to 0 int Number of Children  &CHD=2

 

We would like to present to you an example usage of the endpoint. For this purpose let's continue with the last example described in Timetable API.
Our user is a man and he wants to organize a flight in May from Dublin to Wrocław for himself and his daughter. Hence let's sum up:

  • departure is on 1st of May, 2017
  • passenger is adult, second passenger is child
  • he wants to get back in 4-6 days

To fulfil the assumptions we need to set following parameters:

  • Origin=DUB
  • Destination=WRO
  • DateOut=2017-05-01
  • DateIn=2017-05-06
  • ADT=1
  • CHD=1
  • RoundTrip=true
  • FlexDaysIn=2

Let's build up our request:

curl -X GET "http://fraas-prod.apigee.net/pub/v1/reservations/AvailabilityV2?ADT=1&CHD=1&DateIn=2017-05-06&DateOut=2017-05-01&Destination=WRO&FlexDaysIn=2&Origin=DUB&RoundTrip=true&apikey={apikey}"

We get following result after running this command:

{
  "currency": "EUR",
  "currPrecision": 2,
  "trips": [
    {
      "origin": "DUB",
      "originName": "Dublin T1",
      "destination": "WRO",
      "destinationName": "Wroclaw",
      "dates": [
        {
          "dateOut": "2017-05-01T00:00:00.000",
          "flights": [
            {
              "flightNumber": "FR 1926",
              "time": [
                "2017-05-01T09:45:00.000",
                "2017-05-01T13:20:00.000"
              ],
              "timeUTC": [
                "2017-05-01T08:45:00.000Z",
                "2017-05-01T11:20:00.000Z"
              ],
              "duration": "02:35",
              "faresLeft": -1,
              "flightKey": "FR~1926~ ~~DUB~05/01/2017 09:45~WRO~05/01/2017 13:20~",
              "infantsLeft": 18,
              "regularFare": {
                "fareKey": "0~A~~AZ10LOW~BO10~~1~X",
                "fareClass": "A",
                "fares": [
                  {
                    "type": "ADT",
                    "amount": 45.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 45.99,
                    "mandatorySeatFee": {
                      "code": "SETA",
                      "qty": 1,
                      "vat": 0,
                      "amt": 4,
                      "total": 4
                    },
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  },
                  {
                    "type": "CHD",
                    "amount": 45.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 45.99,
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "origin": "WRO",
      "originName": "Dublin T1",
      "destination": "DUB",
      "destinationName": "Wroclaw",
      "dates": [
        {
          "dateOut": "2017-05-06T00:00:00.000",
          "flights": []
        },
        {
          "dateOut": "2017-05-07T00:00:00.000",
          "flights": [
            {
              "flightNumber": "FR 1927",
              "time": [
                "2017-05-07T21:25:00.000",
                "2017-05-07T23:05:00.000"
              ],
              "timeUTC": [
                "2017-05-07T19:25:00.000Z",
                "2017-05-07T22:05:00.000Z"
              ],
              "duration": "02:40",
              "faresLeft": -1,
              "flightKey": "FR~1927~ ~~WRO~05/07/2017 21:25~DUB~05/07/2017 23:05~",
              "infantsLeft": 18,
              "regularFare": {
                "fareKey": "0~V~~VZ10LOW~BO10~~1~X",
                "fareClass": "V",
                "fares": [
                  {
                    "type": "ADT",
                    "amount": 76.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 76.99,
                    "mandatorySeatFee": {
                      "code": "SETA",
                      "qty": 1,
                      "vat": 0,
                      "amt": 4,
                      "total": 4
                    },
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  },
                  {
                    "type": "CHD",
                    "amount": 76.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 76.99,
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  }
                ]
              }
            }
          ]
        },
        {
          "dateOut": "2017-05-08T00:00:00.000",
          "flights": [
            {
              "flightNumber": "FR 1927",
              "time": [
                "2017-05-08T13:45:00.000",
                "2017-05-08T15:25:00.000"
              ],
              "timeUTC": [
                "2017-05-08T11:45:00.000Z",
                "2017-05-08T14:25:00.000Z"
              ],
              "duration": "02:40",
              "faresLeft": -1,
              "flightKey": "FR~1927~ ~~WRO~05/08/2017 13:45~DUB~05/08/2017 15:25~",
              "infantsLeft": 18,
              "regularFare": {
                "fareKey": "0~V~~VZ10LOW~BO10~~1~X",
                "fareClass": "V",
                "fares": [
                  {
                    "type": "ADT",
                    "amount": 76.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 76.99,
                    "mandatorySeatFee": {
                      "code": "SETA",
                      "qty": 1,
                      "vat": 0,
                      "amt": 4,
                      "total": 4
                    },
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  },
                  {
                    "type": "CHD",
                    "amount": 76.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 76.99,
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "serverTimeUTC": "2017-01-19T16:26:25.108Z"
}

The response looks a little bit too big to digest it in one piece, let's cut it in to two data chunks - outbound flight and inbound flights. 

Outbound flight:

{
      "origin": "DUB",
      "originName": "Dublin T1",
      "destination": "WRO",
      "destinationName": "Wroclaw",
      "dates": [
        {
          "dateOut": "2017-05-01T00:00:00.000",
          "flights": [
            {
              "flightNumber": "FR 1926",
              "time": [
                "2017-05-01T09:45:00.000",
                "2017-05-01T13:20:00.000"
              ],
              "timeUTC": [
                "2017-05-01T08:45:00.000Z",
                "2017-05-01T11:20:00.000Z"
              ],
              "duration": "02:35",
              "faresLeft": -1,
              "flightKey": "FR~1926~ ~~DUB~05/01/2017 09:45~WRO~05/01/2017 13:20~",
              "infantsLeft": 18,
              "regularFare": {
                "fareKey": "0~A~~AZ10LOW~BO10~~1~X",
                "fareClass": "A",
                "fares": [
                  {
                    "type": "ADT",
                    "amount": 45.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 45.99,
                    "mandatorySeatFee": {
                      "code": "SETA",
                      "qty": 1,
                      "vat": 0,
                      "amt": 4,
                      "total": 4
                    },
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  },
                  {
                    "type": "CHD",
                    "amount": 45.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 45.99,
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  }
                ]
              }
            }
          ]
        }
      ]
    }

To analyze available flights we should look in JSON property flights. There is only one flight available - that's because we set DateOut parameter and didn't set any flexibility for this outbound flight. Inside this property we see a bunch of other important flight details:

  • departure is at 9:45, 1st of May, 2017
  • flight number is FR 1926
  • flight duration is 2:35h
  • fares for regular ticket for adult and child (in ohter queries there might be also business and laisure fares)

Now, let's have a look at second piece:

{
      "origin": "WRO",
      "originName": "Dublin T1",
      "destination": "DUB",
      "destinationName": "Wroclaw",
      "dates": [
        {
          "dateOut": "2017-05-06T00:00:00.000",
          "flights": []
        },
        {
          "dateOut": "2017-05-07T00:00:00.000",
          "flights": [
            {
              "flightNumber": "FR 1927",
              "time": [
                "2017-05-07T21:25:00.000",
                "2017-05-07T23:05:00.000"
              ],
              "timeUTC": [
                "2017-05-07T19:25:00.000Z",
                "2017-05-07T22:05:00.000Z"
              ],
              "duration": "02:40",
              "faresLeft": -1,
              "flightKey": "FR~1927~ ~~WRO~05/07/2017 21:25~DUB~05/07/2017 23:05~",
              "infantsLeft": 18,
              "regularFare": {
                "fareKey": "0~V~~VZ10LOW~BO10~~1~X",
                "fareClass": "V",
                "fares": [
                  {
                    "type": "ADT",
                    "amount": 76.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 76.99,
                    "mandatorySeatFee": {
                      "code": "SETA",
                      "qty": 1,
                      "vat": 0,
                      "amt": 4,
                      "total": 4
                    },
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  },
                  {
                    "type": "CHD",
                    "amount": 76.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 76.99,
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  }
                ]
              }
            }
          ]
        },
        {
          "dateOut": "2017-05-08T00:00:00.000",
          "flights": [
            {
              "flightNumber": "FR 1927",
              "time": [
                "2017-05-08T13:45:00.000",
                "2017-05-08T15:25:00.000"
              ],
              "timeUTC": [
                "2017-05-08T11:45:00.000Z",
                "2017-05-08T14:25:00.000Z"
              ],
              "duration": "02:40",
              "faresLeft": -1,
              "flightKey": "FR~1927~ ~~WRO~05/08/2017 13:45~DUB~05/08/2017 15:25~",
              "infantsLeft": 18,
              "regularFare": {
                "fareKey": "0~V~~VZ10LOW~BO10~~1~X",
                "fareClass": "V",
                "fares": [
                  {
                    "type": "ADT",
                    "amount": 76.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 76.99,
                    "mandatorySeatFee": {
                      "code": "SETA",
                      "qty": 1,
                      "vat": 0,
                      "amt": 4,
                      "total": 4
                    },
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  },
                  {
                    "type": "CHD",
                    "amount": 76.99,
                    "count": 1,
                    "hasDiscount": false,
                    "publishedFare": 76.99,
                    "discountInPercent": 0,
                    "hasPromoDiscount": false
                  }
                ]
              }
            }
          ]
        }
      ]
    }

What we get from second piece is basically the same type of information as in first one. One difference is the number of proposed flights. The reason for that is the FlexDaysIn parameter - we set that to 2 which means we wanted to get possible flights for two next days as well.