Wego Flights API documentation

Wego's Flights Search Service allows clients to search for flight fares and availabilty in real-time across Wego's inventory of partners. The service is available via standard HTTP GET methods and responses are made available in both XML and JSON formats.

Please report any bugs to api@wego.com.

Table of Contents

Change Logs

Core Concepts

What can you do with the API?

There are 3 main components that you'll most likely care about:

  1. Search
    Allows you to start a flight search and retrieve results

  2. Booking a flight with our partners
    Taking users to continue the booking process for a flight at one of our partners' sites

  3. API usage
    The flights API only allow users to make a certain number of calls per hour. Therefore, you would most likely want to check how many calls you have already made.

The typical use case of a user searching for Flights would involve:

  1. A user, let's call her Yui, is looking for Economy class flights to fly from Singapore to Bangkok on 23 June 2010 and She is thinking of coming back to Singapore on 26 June 2010. She fill in the relevant fields on the search form and submit her search to your application.

  2. You first issue a call to check how many calls you have made within the hour.

    GET http://www.wego.com/api/flights/usage.html?format=json&apiKey=testAPIKey

    The API responds with: 

        {"APIUsageData": {
    "usageCount": {
    "value": 0
    },
    "maxCount": {
    "value": 1000
    },
    "startTimeBucket": "20100612230038",
    "endTimeBucket": "20100613000038"
    }}

  3. After checking that you are still within the API limit, you can start using the API. You send a startSearch API /startSearch.html request to start a search for flights meeting her requirement. (If custom ts_code is given, please add the ts_code=VALUE to the parameter.)

    GET http://www.wego.com/api/flights/startSearch.html?format=json&fromLocation=SIN&toLocation=BKK&tripType=roundTrip&cabinClass=Economy&inboundDate=2010-06-26&outboundDate=2010-06-23&numAdults=1&apiKey=testApiKey&ts_code=a7557

    The API responds with: 

        {"request":{
    "instanceId":"ec08ea02b4946dabbbc800da0835c696f1c5a6ac"
    ,"usage":"1"
    }
    }

    you can then use the instanceId to fetch search results with the /pull.html API method.

    To use the /pull.html method, A rand parameter need to be passed in together with the instanceId parameter to form a unique key that will keep track of number of results returned to Yui.

    Important: If you wish to start polling from the very first result then issue a new rand value, otherwise continue using the same rand till you reach the end of result list.

    GET http://www.wego.com/api/flights/pull.html?format=json&apiKey=testApiKey&instanceId=c90a013e708e5ffcc526dd81ac42acf5f6040739&rand=1

    the API responds with: 

        {"response":{
    "pendingResults":"true",
    "itineraries":[
    "{"itinerary":{
    "originCountryCode": "SG",
    "destinationCountryCode": "TH",
    "price": {
    "amount": "380.0",
    "currencyCode": "SGD",
    "includesTax": true,
    "name": "",
    "pricePerPassenger": "380.0",
    "totalAmount": "510.3",
    "totalPricePerPassenger": "510.3"
    },
    "outboundInfo": {
    "aircraftTypes": ["772"],
    "airports": ["SIN", "BKK"],
    "arrivalTime": 1287829500000,
    "departureTime": 1287820800000,
    "durationInMin": 145,
    "flightClasses": [{
    "fareClass": 1,
    "name": "Economy"
    }],
    "flightNumbers": ["SQ976"],
    "layoverInMin": 0,
    "localArrivalTimeStr": "2010/10/23 17:25 +0700",
    "localDepartureTimeStr": "2010/10/23 16:00 +0800",
    "numStops": 0
    },
    "inboundInfo": {
    "aircraftTypes": ["772"],
    "airports": ["BKK", "SIN"],
    "arrivalTime": 1288101300000,
    "departureTime": 1288092600000,
    "durationInMin": 145,
    "flightClasses": [{
    "fareClass": 1,
    "name": "Economy"
    }],
    "flightNumbers": ["SQ979"],
    "layoverInMin": 0,
    "localArrivalTimeStr": "2010/10/26 21:55 +0800",
    "localDepartureTimeStr": "2010/10/26 18:30 +0700",
    "numStops": 0
    },
    "carrier": [{
    "code": "SQ",
    "name": "Singapore Airlines"
    }],
    "location": [{
    "code": "SIN",
    "name": "Singapore Changi"
    },
    {
    "code": "BKK",
    "name": "Bangkok"
    }],
    "id": "SQ976[SIN-BKK]|SQ979[BKK-SIN]",
    "generatedDate": 1287063322786,
    "providerId": "singaporeair.com",
    "bookingCode": "1287063322787172000"
    }",...

  4. Yui is shown a page where results from the /pull.html method are displayed

    It's best to wait at least 10 seconds after starting the search before making the /pull.html call.

    To retrieve all the results, you would have call the /pull.html until the response return a false for the pendingResults field

  5. Yui wants to view more flight details like transit airport. You send a details /details.html request.

    GET http://www.wego.com/api/flights/details.html?instanceId=c90a013e708e5ffcc526dd81ac42acf5f6040739&itineraryId=CX712[SIN-BKK]|CX713[BKK-SIN]&format=json&outboundDate=2010-06-23&inboundDate=2010-06-26&apiKey=testApiKey

    the API responds with: 

        {"details": {"outboundSegments": {"list": [
    {
    "flightNumber": {
    "designator": "CX",
    "number": "712"
    },
    "operatingAirlineFlightNumber": {
    "designator": "CX",
    "number": "712"
    },
    "departureStation": "SIN",
    "passengerSTD": "1355",
    "STD": "1355",
    "UTCLocalDepartureTimeVariation": "+0800",
    "passengerDepartureTerminal": "1",
    "arrivalStation": "BKK",
    "STA": "1515",
    "passengerSTA": "1515",
    "UTCLocalArrivalTimeVariation": "+0700",
    "aircraftType": "773",
    "operatorCode": "CX",
    "durationInMin": 140,
    "departureDateTime": 1295502900000,
    "arrivalDateTime": 1295511300000
    }
    ]}, "inboundSegments": {"list": [
    {
    "flightNumber": {
    "designator": "CX",
    "number": "713"
    },
    "operatingAirlineFlightNumber": {
    "designator": "CX",
    "number": "713"
    },
    "departureStation": "BKK",
    "passengerSTD": "1245",
    "STD": "1245",
    "UTCLocalDepartureTimeVariation": "+0700",
    "arrivalStation": "SIN",
    "STA": "1610",
    "passengerSTA": "1610",
    "UTCLocalArrivalTimeVariation": "+0800",
    "passengerArrivalTerminal": "1",
    "aircraftType": "773",
    "operatorCode": "CX",
    "durationInMin": 145,
    "departureDateTime": 1298612700000,
    "arrivalDateTime": 1298621400000
    }
    ]} }}

  6. Yui sees a Flight (bookingCode 1276355338783763000, providerId airasia.com ) that she would like to book and clicks to continue to book the flight at the partner site.

  7. You send a book API /redirect.html request to retrieve a handoff page that redirect the user to the booking site of the partner so that she can continue her booking directly with them:

    GET http://www.wego.com/api/flights/redirect.html?apiKey=testAPIKey&bookingCode=1276355338783763000&providerId=airasia.com&dlfrom=SIN&dlto=BKK&instanceId=c90a013e708e5ffcc526dd81ac42acf5f6040739&ts_code=a7557

One Way UI

Another approach to presenting the data is to offer users two one-way tickets for the outbound and inbound legs. To do this, you will need to follow the same approach as above, but instead of doing a roundtrip search, you will have to send two one-way searches for the outbound and inbound legs. You will then need to handle the results from the two requests in such a way that you will be able to offer the users the flexibility to create their own itinerary by mixing and matching leg options.

An example of this kind of layout could be seen here.

Please note that you can do this in any city pairs you like if the majority of carriers serving those routes offer one-way pricing.

Authentication/Rate-limiting

All API requests require you to authenticate with your API Key(given to you by Wego). Always pass along the apiKey in your API requests, Example

GET http://www.wego.com/api/flights/usage.html?format=json&apiKey=testAPIKey

Your API key is used to track usage and to limit the number of API requests you can make (for all API methods except the usage API /usage.html). The API rate limits have not been decided at this time

Response Types

Itinerary

The itinerary type represents a single flight search result that matches the user requirement

A sample itinerary response in JSON looks like: 

      "itinerary":{
      "originCountryCode": "SG",
      "destinationCountryCode": "TH",
      "price": {
      "amount": "380.0",
      "currencyCode": "SGD",
      "includesTax": true,
      "name": "",
      "pricePerPassenger": "380.0",
      "totalAmount": "510.3",
      "totalPricePerPassenger": "510.3"
      },
      "outboundInfo": {
      "aircraftTypes": ["772"],
      "airports": ["SIN", "BKK"],
      "arrivalTime": 1287829500000,
      "departureTime": 1287820800000,
      "durationInMin": 145,
      "flightClasses": [{
      "fareClass": 1,
      "name": "Economy"
      }],
      "flightNumbers": ["SQ976"],
      "layoverInMin": 0,
      "localArrivalTimeStr": "2010/10/23 17:25 +0700",
      "localDepartureTimeStr": "2010/10/23 16:00 +0800",
      "numStops": 0
      },
      "inboundInfo": {
      "aircraftTypes": ["772"],
      "airports": ["BKK", "SIN"],
      "arrivalTime": 1288101300000,
      "departureTime": 1288092600000,
      "durationInMin": 145,
      "flightClasses": [{
      "fareClass": 1,
      "name": "Economy"
      }],
      "flightNumbers": ["SQ979"],
      "layoverInMin": 0,
      "localArrivalTimeStr": "2010/10/26 21:55 +0800",
      "localDepartureTimeStr": "2010/10/26 18:30 +0700",
      "numStops": 0
      },
      "carrier": [{
      "code": "SQ",
      "name": "Singapore Airlines"
      }],
      "location": [{
      "code": "SIN",
      "name": "Singapore Changi"
      },
      {
      "code": "BKK",
      "name": "Bangkok"
      }],
      "id": "SQ976[SIN-BKK]|SQ979[BKK-SIN]",
      "generatedDate": 1287063322786,
      "providerId": "singaporeair.com",
      "bookingCode": "1287063322787172000"
      },

Details

The details type represents the detailed information of a single itinerary

A sample details response in JSON looks like: 

      {"details": {"outboundSegments": {"list": [
    {
    "flightNumber": {
    "designator": "CX",
    "number": "712"
    },
    "operatingAirlineFlightNumber": {
    "designator": "CX",
    "number": "712"
    },
    "departureStation": "SIN",
    "passengerSTD": "1355",
    "STD": "1355",
    "UTCLocalDepartureTimeVariation": "+0800",
    "passengerDepartureTerminal": "1",
    "arrivalStation": "BKK",
    "STA": "1515",
    "passengerSTA": "1515",
    "UTCLocalArrivalTimeVariation": "+0700",
    "aircraftType": "773",
    "operatorCode": "CX",
    "durationInMin": 140,
    "departureDateTime": new Date(1295502900000),
    "arrivalDateTime": new Date(1295511300000)
    }
    ]}, "inboundSegments": {"list": [
    {
    "flightNumber": {
    "designator": "CX",
    "number": "713"
    },
    "operatingAirlineFlightNumber": {
    "designator": "CX",
    "number": "713"
    },
    "departureStation": "BKK",
    "passengerSTD": "1245",
    "STD": "1245",
    "UTCLocalDepartureTimeVariation": "+0700",
    "arrivalStation": "SIN",
    "STA": "1610",
    "passengerSTA": "1610",
    "UTCLocalArrivalTimeVariation": "+0800",
    "passengerArrivalTerminal": "1",
    "aircraftType": "773",
    "operatorCode": "CX",
    "durationInMin": 145,
    "departureDateTime": new Date(1298612700000),
    "arrivalDateTime": new Date(1298621400000)
    }
    ]} }}

Errors

The API returns appropriate HTTP status codes. In addition, the API also includes error information in the response body. Error responses have a single error property that is a string describing the error, e.g.:

{"error": {"message": "apiKey:testApiKey does not have a valid session"}}

An additional message property is sometimes available for further diagnostics.

Possible errors are:

API Methods

All API methods are HTTP GET requests and require API key-based authentication. The response data format is in either JSON or XML.

Request Description Example
/startSearch.html Start a new flight Search http://www.wego.com/api/flights/startSearch.html?format=json&fromLocation=SIN&toLocation=BKK&tripType=roundTrip&cabinClass=Economy&inboundDate=2010-06-26&outboundDate=2010-06-23&numAdults=1&apiKey=testApiKey
/pull.html Retrieve the results of the search http://www.wego.com/api/flights/pull.html?format=json&apiKey=testApiKey&instanceId=c90a013e708e5ffcc526dd81ac42acf5f6040739&rand=1
/details.html Retrieve the detailed Flights Information of an Itinerary http://www.wego.com/api/flights/details.html?instanceId=c90a013e708e5ffcc526dd81ac42acf5f6040739&itineraryId=CX712[SIN-BKK]|CX713[BKK-SIN]&format=json&outboundDate=2010-06-23&inboundDate=2010-06-26&apiKey=testApiKey
/redirect.html Redirect the user to the partner page for booking http://www.wego.com/api/flights/redirect.html?apiKey=testAPIKey&bookingCode=1271214629587733000&providerId=singaporeair.com&dlfrom=SIN&dlto=BKK&instanceId=22c90a013e708e5ffcc526dd81ac42acf5f604073&ts_code=a7557
/usage Check the usage for an apiKey http://www.wego.com/api/flights/usage?format=json&apiKey=testAPIKey

/startSearch.html- Start a new Flight Search

Start a new Flight Search

GET http://www.wego.com/api/flights/startSearch.html?format=format&fromLocation=departureAirportCode&toLocation=arrivalAirportCode&tripType=tripType&cabinClass=cabinClass&inboundDate=inboundDate&outboundDate=outboundDate&numAdults=numAdults&numChildren=numChildren&callback=callback&apiKey=APIKey&ts_code=ts_code

Example: http://www.wego.com/api/flights/startSearch.html?format=json&fromLocation=SIN&toLocation=BKK&tripType=roundTrip&cabinClass=Economy&inboundDate=2010-06-26&outboundDate=2010-06-23&numAdults=1&apiKey=testApiKey

Parameters:

Return the instanceId for the flight search 

      {"request":{
      "instanceId":"ec08ea02b4946dabbbc800da0835c696f1c5a6ac"
      ,"usage":"1"
      }
      }

/pull.html - Retrieving the results of a Flight Search

Retrieving the result of a flight search

GET http://www.wego.com/api/flights/pull.html?format=format&apiKey=APIKey&instanceId=instanceId&rand=random&callback=callback

Example: http://www.wego.com/api/flights/pull.html?format=json&apiKey=testApiKey&instanceId=c90a013e708e5ffcc526dd81ac42acf5f6040739&rand=1

Parameters:

Return an array of Itinerary Object and the following key-values 

      {"response":{
      "pendingResults":"true",
      "itineraries":[
      {
      "originCountryCode": "SG",
      "destinationCountryCode": "TH",
      "price": {
      "amount": "380.0",
      "currencyCode": "SGD",
      "includesTax": true,
      "name": "",
      "pricePerPassenger": "380.0",
      "totalAmount": "510.3",
      "totalPricePerPassenger": "510.3"
      },
      "outboundInfo": {
      "aircraftTypes": ["772"],
      "airports": ["SIN", "BKK"],
      "arrivalTime": 1287829500000,
      "departureTime": 1287820800000,
      "durationInMin": 145,
      "flightClasses": [{
            "fareClass": 1,
            "name": "Economy"
      }],
      "flightNumbers": ["SQ976"],
      "layoverInMin": 0,
      "localArrivalTimeStr": "2010/10/23 17:25 +0700",
      "localDepartureTimeStr": "2010/10/23 16:00 +0800",
      "numStops": 0
      },
      "inboundInfo": {
      "aircraftTypes": ["772"],
      "airports": ["BKK", "SIN"],
      "arrivalTime": 1288101300000,
      "departureTime": 1288092600000,
      "durationInMin": 145,
      "flightClasses": [{
            "fareClass": 1,
            "name": "Economy"
      }],
      "flightNumbers": ["SQ979"],
      "layoverInMin": 0,
      "localArrivalTimeStr": "2010/10/26 21:55 +0800",
      "localDepartureTimeStr": "2010/10/26 18:30 +0700",
      "numStops": 0
      },
      "carrier": [{
      "code": "SQ",
      "name": "Singapore Airlines"
      }],
      "location": [{
      "code": "SIN",
      "name": "Singapore Changi"
      },
      {
      "code": "BKK",
      "name": "Bangkok"
      }],
      "id": "SQ976[SIN-BKK]|SQ979[BKK-SIN]",
      "generatedDate": 1287063322786,
      "providerId": "singaporeair.com",
      "bookingCode": "1287063322787172000"
      }}}",...

/details.html - Retrieving detailed information about a flight itinerary

Retrieving the detailed information of a flight itinerary

GET http://www.wego.com/api/flights/details.html?instanceId=instanceId&itineraryId=itineraryId&format=format&outboundDate=outboundDate&inboundDate=inboundDate&apiKey=APIKey&callback=callback

Example: http://www.wego.com/api/flights/details.html?instanceId=c90a013e708e5ffcc526dd81ac42acf5f6040739&itineraryId=CX712[SIN-BKK]|CX713[BKK-SIN]&format=json&outboundDate=2010-06-23&inboundDate=2010-06-26&apiKey=testApiKey

Parameters:

Return Details Object 

      {"details": {"outboundSegments": {"list": [
      {
      "flightNumber": {
      "designator": "CX",
      "number": "712"
      },
      "operatingAirlineFlightNumber": {
      "designator": "CX",
      "number": "712"
      },
      "departureStation": "SIN",
      "passengerSTD": "1355",
      "STD": "1355",
      "UTCLocalDepartureTimeVariation": "+0800",
      "passengerDepartureTerminal": "1",
      "arrivalStation": "BKK",
      "STA": "1515",
      "passengerSTA": "1515",
      "UTCLocalArrivalTimeVariation": "+0700",
      "aircraftType": "773",
      "operatorCode": "CX",
      "durationInMin": 140,
      "departureDateTime": 1295502900000,
      "arrivalDateTime": 1295511300000
      }
      ]}, "inboundSegments": {"list": [
      {
      "flightNumber": {
      "designator": "CX",
      "number": "713"
      },
      "operatingAirlineFlightNumber": {
      "designator": "CX",
      "number": "713"
      },
      "departureStation": "BKK",
      "passengerSTD": "1245",
      "STD": "1245",
      "UTCLocalDepartureTimeVariation": "+0700",
      "arrivalStation": "SIN",
      "STA": "1610",
      "passengerSTA": "1610",
      "UTCLocalArrivalTimeVariation": "+0800",
      "passengerArrivalTerminal": "1",
      "aircraftType": "773",
      "operatorCode": "CX",
      "durationInMin": 145,
      "departureDateTime": 1298612700000,
      "arrivalDateTime": 1298621400000
      }
      ]} }}

/redirect.html - Redirect to a partner site for booking

Get a page that redirect to one of our partners' site for booking. The result is a HTML page that redirects to one of our partner site, not JSON/XML

GET http://www.wego.com/api/flights/redirect.html?apiKey=APIKey&bookingCode=bookingCode&providerId=providerId&dlfrom=origin&dlto=destination&instanceId=instanceId&ts_code=a7557

Example: http://www.wego.com/api/flights/redirect.html?format=json&apiKey=testAPIKey&bookingCode=1271214629587733000&providerId=singaporeair.com&dlfrom=SIN&dlto=BKK&instanceId=c90a013e708e5ffcc526dd81ac42acf5f604073&ts_code=a7557

Parameters:

/usage.html - Check usage of API

Allows you to check the usage of the API

GET http://www.wego.com/api/flights/usage.html?format=format&apiKey=APIKey&callback=callback

Example: http://www.wego.com/api/flights/usage.html?format=json&apiKey=testAPIKey

Parameters:

The response indicate the current API Usage Example: 

      {"APIUsageData": {
      "usageCount": {
      "value": 0
      },
      "maxCount": {
      "value": 1000
      },
      "startTimeBucket": "20100612230038",
      "endTimeBucket": "20100613000038"
      }}