Connection Guide

How to Connect to the V2 API services

XML API URL: http://api.travelfusion.com/api-v2/

A tool for trying out the API can be found at: XML Test Tool

An example interface implementation can be found at Beta Site

XML data is submitted as the body of a standard HTTP 1.0 (or HTTPS) POST request. SSL (HTTPS) must be used for all requests. HTTPS is used automatically for any URL beginning with "https:" instead of "http:". In general, UTF-8 encoding should be used. GZip compression must be requested in all HTTP requests. See this example. (But please note that Travelfusion's servers may not always return gzip compressed results.)

Authentication is achieved by adding an attribute called ‘token’ to the top level element of all requests. The value of the token must be that returned in the LoginResponse (see below). The same token can be used for all requests for all users and sessions, until it expires. Users MUST refresh the token every 12 hours by submitting a new LoginRequest to obtain a new token. Additionally, users must refresh the token if after submitting any request they receive an ErrorResponse with message "Token has expired or doesn't exist."

The namespace must be specified as an attribute of every XML request: xmlns="http://www.travelfusion.com/xml/api/simple". 

Any cookies returned in the response headers should be submitted in all subsequent requests in the same user session as per the HTTP spec. These cookies are used to ensure the same server is used for handling all XML requests in the same session. See this example.

An 'lang' attribute may be added to the top level element of ANY request, to request the response to be in a particular language where possible/ applicable. e.g. lang="sv". The language codes are available here.

Obtaining a Login Token

Request

<LoginRequest xmlns="http://www.travelfusion.com/xml/api/simple">

   <username>********</username>

   <password>********</password>

</LoginRequest>

A valid username and password must be submitted.

Response

<LoginResponse xmlns="http://www.travelfusion.com/xml/api/simple" token="xxxxxxxxxxxxxx"/>

Error Handling [this spec is currently under development. Please ignore this section]

Travelfusion endeavour to detect and identify common causes of errors wherever possible. If an error is identified, the response will be of the following format:

<ErrorResponse errorCode="123">

        <!-- a simple message that could be displayed to the end user -->

    <textForEndUser>Your session has expired. Please start a fresh search.</textForEndUser>

        <!-- a simple description of the error's meaning and possible solution, for explanation to a developer -->

    <textForDeveloper>Session token not found - either a bad token or session expired. Possibly related to incorrect cookie usage causing wrong app server to be hit</textForDeveloper>

    <reproductionInfo>

        <!-- information to aid reproduction - e.g. the XML request that caused the problem    

    </reproductionInfo>

    <debugInfo>

        <!-- Free text information about the error such as stacktrace etc -->

    </debugInfo>

</ErrorResponse>

If an unexpected response is received (i.e. not matching the defined response format or the above error format, the response should be logged along with the request that caused it (in cases of polling, the initial search request should be logged too). The error should then be investigated by:

i) Checking the request to ensure it adheres to the specification

ii) Checking the response to see why it caused a problem for your system - it is possible that the response is correct but your system parsed or handled it incorrectly.

iii) If the request appears valid and the response appears to be invalid, it should be reported to Travelfusion along with the logs for investigation.

An XML command will be provided which will return all the possible error codes, to aid development. This should not be used at runtime.

  

General Guidelines

- Currencies are always represented/ expected as the standard 3-letter currency code in CAPS

- None of our APIs are to be accessed in an automated or robotic way. Every XML request must be directly initiated as a result of a real user action or update, except polling and token requests.

Alternative Formats

Two other methods are supported for the submission and return of XML data. These are detailed below.

Submitting XML as parameters to a GET URL

The full structure of the XML is reflected for each element by concatenating all of its ancestor elements using the ‘.’ separator. Attributes can be treated the same as child elements. For example to submit the following XML:

<GetHotelsRequest xmlns="http://www.travelfusion.com/xml/api/simple" token="sdjkr348573498" lang="sv">

    <location>

        <city code="LON"/>

    </location>

    <date>2012-01-11</date>

    <duration>7</duration>

    <rooms>

        <room>

            <ages>

                <age>30</age>

                <age>1</age>

            </ages>

        </room>

        <room>

            <ages>

                <age>30</age>

            </ages>

        </room>

    </rooms>

</GetHotelsRequest>

The equivalent GET URL is constructed as follows:

http://mirrorapi.travelfusion.com/api-v2/simple/GetHotelsRequest?token=sdjkr348573498&lang=se&location.city.code=LON&date=2011-11-11&duration=7&rooms.room[0].ages.age[1]=30&rooms.room[0].ages.age[1]=1&rooms.room[1].ages.age[0]=30

The parameter names and values should not be xml-encoded, but they should be url-encoded. For each element, an index must be appended (in this format: [0]) to the name, indicating the index of that element among other elements with the same name and the same parent. (If the index is omitted, it will be assumed there is only one element with that name and parent). In the URL itself, note that “/simple/GetLiveHotelOffersRequest” has been appended to the usual XML URL. This indicates the namespace (the xmlns attribute of the top level element of the XML, omitting the base URL ‘http://www.travelfusion.com/xml/api/’), and the XML element name of the top level element. Don't forget to use HTTPS for sensitive data.

Using JSON or JSON-P format

This is requested by adding attribute ‘responseType’ to the top level element with value ‘json’ or ‘jsonp’.  In the case of  JSON-P, another attribute must be submitted named ‘callback’, which should be set to the name of your own javascript function that should be called once the response is received. For example, to receive a JSON-P response when submitting a location resolution request: 

<ResolveLocationRequest xmlns="__" token="temp" responseType="jsonp" callback="processResponse">

        <text>lon</text>

</ResolveLocationRequest>

Note that JSON and JSONP have inherent problems and Travelfusion cannot take responsibility for any issues within the related 3rd party libraries or the standard itself. It is recommended that the pure XML solution is utilised.

You must not use JSON or JSONP without permission in advance from Travelfusion.

The JSON library currently used by Travelfusion handles single element arrays in an unusual way. The parent array element is completely omitted. Please make sure you find an example and check that your application handles this correctly in general for all the possible array elements. You should also ensure that your application will handle the proper 1-element array syntax. Other libraries have been tried but each had its own flaws.

Travelfusion will not accept bug reports where the example requests/ responses are provided in JSON format. Also, before reporting a bug, you must try the same request as pure XML so that you can report whether the problem is JSON only or affecting the XML service too. If the examples works in XML but not in Json, please state this in the bug report and supply both examples.