XML-Interface-v2

The XML-Interface is the core of the VA Integration Kit. It has been designed to give VA Administrators with the knowledge of dynamic web techniques the possibility to create their own layout and perfectly integrate the information into their own website using data from FSAirlines.

Changes from the previous version

Compared to the previous version of the XML-Interface the following change were made.

• Change from domain registration to API keys.
• Rate limits added.
• Json output format added.
• Output properly supports UTF-8 character set.
• Additional functions for packages added.

Rate limits

The access to the interface is limited by the number of calls an VA can make each hour and each day. An airline with a gold account can make 100 calls each hour and 1200 call each day. An airline with a platinum account can make 500 calls each hour and 6000 call each day. If an airline has multiple members then those limits are added together for each premium account. Example if an airline has one platinum member and two gold member there limits are 700 an hour and 8400 per day. Functions related to pilots booking flights do not count against the rate limits.

Access Restriction

In order to be able to access data from the Data-Interface you need to create an API key, this can be done using the 'Api Key Management' page on the website accessible from the options on the VA overview page. There are two types of API keys that can be created.

Site key: This key is to be used by your main website/service and may be use the full rate limit allowed by your VA. After one hundred calls using a site api key, the key will be locked to the IP address used. If in the future you need to change the IP address all you need to do is delete the old key and create a new one.

Developer key: This key is used to help you create and test your website on a different machine than your main site. It will not be limited to a single IP address but will be limited to the number of calls each day your VA is normally allowed each hour. Usage of the developer key does apply against your VA's total rate limit.

Basic Usage

The data can be received using HTTP calls to the interface script and add the desired function to the parameters. Here is an example request:

http://www.fsairlines.net/va_interface2.php?function=getPilotList&va_id=7&apikey=xxxxx

As you can see there is the interface script va_interface.php, the function getPilotList and the parameters va_id=7 and apikey=xxxxx. Some functions require additional parameters, these can be appended after the other parameters.

The result of the request will be given in xml format with the base-tag being <fsa_output>. This tag has the attributes version and success which show the version number of the interface and if the request succeeded or not. In case of a failure the success-attribute shows the error message. The following example shows the return text of the above function:

<fsa_output version="1.0" success="SUCCESS">
  <data id="1" name="Konrad" surname="Pustka" va_user="SNA101" location="EDDM" lastactive="1287330550" budget="198144" />
  <data id="2" name="Claudio" surname="Gusmini" va_user="SNA102" location="EDDM" lastactive="1286366261" budget="216405101" />
</fsa_output>

Inside the fsa_output-tag there are the data-tags which contain all the information.

When calling using this method the default output format is XML, you can get the out in JSON format by adding a format=json parameter to the request. Example:

https://www.fsairlines.net/va_interface2.php?function=getPilotList&va_id=7&format=json&apikey=xxxxx

The output will be:

{
    "status": "SUCCESS",
    "data": [
        {
            "id": 1,
            "name": "Konrad",
            "surname": "Pustka",
            "va_user": "SNA101",
            "location": "ETSE",
            "lastactive": 1600285079,
            "budget": 2400628
        },
        {
            "id": 2,
            "name": "Claudio",
            "surname": "Gusmini",
            "va_user": "SNA102",
            "location": "LIMG",
            "lastactive": 1605458811,
            "budget": 216631042
        }
    ]
}

If you need something to get started here's a small example PHP-script showing a list of your pilots' names. Just replace the va_id by your own.

<?php
  $ch = curl_init("https://www.fsairlines.net/va_interface2.php?function=getPilotList&va_id=7&format=json&apikey=xxxxxx");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  $http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  $http_text = curl_exec($ch);

  $objDOM = new DOMDocument();
  $objDOM->loadXML($http_text);

  $dataNodes = $objDOM->getElementsByTagName("data");
  foreach( $dataNodes as $node )
  {
    $name = $node->getAttribute("name");
    $surname = $node->getAttribute("surname");
    echo "{$name} {$surname} <br/>";
  }

Here is a sample of a PHP script reading the same data in JSON format.

<?php

    $ch = curl_init("https://www.fsairlines.net/va_interface2.php?function=getPilotList&va_id=7&format=json&apikey=xxxxxx");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $http_status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $http_text = curl_exec($ch);
    $json_data = json_decode($http_text, true);
    if ($json_data['status'] == 'SUCCESS') {
        foreach($json_data['data'] as $node) {
            echo "{$node['name']} {$node['surname']}<br/>\n";
        }
    }

Here is a sample of a Python script reading the same data in json format.

    #!/usr/bin/python
    import requests

    r = requests.get("https://www.fsairlines.net/va_interface2.php?function=getPilotList&va_id=7&format=json&apikey=xxxxxx")
    json_data = r.json()
    if json_data['status'] == 'SUCCESS':
        for node in json_data['data']:
            print('{} {}'.format(node['name'], node['surname'])

Pilot Login

Several of the functions require that the pilot calling be logged in. Previous versions of the interface required the call passed the pilots username and a hashed password as parameters. That method has now been discontinued, in this version you will need to call the pilotLogin to create a token that can be used to call functions for that pilot. Unlike other calls in the interface, the pilotLogin function is also a HTTP POST call rather than a GET call. Here is an example of calling the pilotLogin function.

<?php

$post = [
    'user' => 'username',
    'password' => 'xxxxxxxx'
];

$ch = curl_init("https://www.fsairlines.net/va_interface2.php?function=pilotLogin&va_id=7&format=json&apikey=xxxxxx");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);

$http_text = curl_exec($ch);
$data = json_decode($http_text, true);

if ($data['status'] == 'SUCCESS') {
    $fsa_token = $data['data']['token'];
} else {
    die("Login failed");
}

The data returned in this request includes:

Parameter	Meaning
token	The pilots login token.
alt_code	The alternate ICAO code of the airport they are currently located based on there default simulator.
budget	The pilots current budget
default_sim	The pilots default simulator.
location	The FSA offical ICAO code of the airport the pilot is located.
name	The pilots first name
pilot_id	The id number of the pilot.
premium	1 of the pilot is a premium member, 0 if not.
rank	The code for the pilots rank within their VA
rank_id	The id of the pilots rank within their VA
surname	The pilots last or given name
va_id	The ID of the pilots VA
va_status	The pilots within there airline
va_user	The pilots ID within their VA.
weightunit	The pilots default unit of measure (kg or lb). } Data The following section contains a detailed list of all the request-functions with their return values. Lately added options are marked green. Parameters All the request functions use parameters which need to be appended. The following table shows all the parameters and their meaning. Parameter Meaning ac_id ID of the aircraft. Is part of the data received from other functions (e.g. getAircraftList). accept_pp Must be set '1' if Privacy Policy is accepted. acdb_id ID of the aircraft type. Is part of the data received from other functions (e.g. getAircraftList). airport Starting airport. Where the user should be placed first. arr ICAO code of the arrival airport. count Number past flights which should be displayed. country Name of the country. days Number of past days from now which should be displayed. dep ICAO code of the departure airport. email E-Mail of the user. fleet_id ID of the fleet. Is part of the data received from other functions. from_ts UNIX timestamp of the date where the listing should start. givenname Given name of the user. icao ICAO code of the airport. pilot_id ID of the pilot. Is part of the data received from other functions. report_id ID of the report. Is part of the data received from other functions. surname Surname of the user. to_ts UNIX timestamp of the date where the listing should end. user Username of the pilot. token Login token created by the pilotLogin function. va_id ID of the Virtual Airline. Is displayed on the Overview page. Aircraft Data Function Parameters Return Codes Data getAircraftData va_id, ac_id SUCCESS, NOT FOUND id, va_id, acdb_id, location, va_id, user_id, lease_id, fleet_id, status, value, registration, fuel, state, ac_name, stateeng1, stateeng2, stateeng3, stateeng4, stategear, statehull, img_path, pax_economy, pax_business, pax_first, config_name getAircraftDBData va_id, acdb_id SUCCESS, NOT FOUND id, manufacturer, type, icao, passengers, price, fuel, dow, mtow, speed, engines, cargo, mzfw, market_only, range getAircraftDBList va_id SUCCESS, NOT FOUND id, manufacturer, type, icao getAircraftList va_id SUCCESS, NOT FOUND id, acdb_id, icao, value, location, registration, state, ac_name, status, fleet_id, fuel getAircraftStats va_id, ac_id SUCCESS, NOT FOUND flights, hours, distance getFleetAircraftList va_id, fleet_id SUCCESS, NOT FOUND id, acdb_id, icao, value, location, registration, state, ac_name, status, fleet_id, fuel getFleetList va_id SUCCESS, NOT FOUND id, name getFleetStats va_id SUCCESS, NOT FOUND id, flights, hours, distance, last, fuel_used, profit, cargo_kg, pax getLeasedAircraftList va_id SUCCESS, NOT FOUND id, acdb_id, icao, value, location, registraion, state, ac_name, status, fleet_id, fuel, va_id, name, expire getPeriodFleetStats va_id, from_ts, to_ts SUCCESS, NOT FOUND id, flights, hours, distance, last, fuel_used, profit, cargo_kg, pax Airport Data Function Parameters Return Codes Data getAirportData va_id, icao SUCCESS, NOT FOUND id, name, iata, icao, city, country, la_g, la_p, la_s, la_d, lat, lo_g, lo_p, lo_s, lo_d, lon, altitude, length, fuel, size getAirportList va_id SUCCESS, NOT FOUND icao, name, city, country, fuel, lat, lon Airline Data Function Parameters Return Codes Data getAirlineData va_id, id (=va_id) SUCCESS, NOT FOUND id, name, base, code, budget, homepage, logo_l, logo_s, price (deprecated, will be removed in next release), reputation, pilotcharge, multiplier, mission getAirlineStats va_id SUCCESS, NOT FOUND id, flights, rating, hours, distance, last, fuel_used, pax, cargo_kg getCountryStats va_id, country SUCCESS, NOT FOUND va_name, id, flights, rating hours, profit, distance, last, fuel_used, pax, cargo_kg getRankList va_id SUCCESS, NOT FOUND id, name, short, settings, pilots, aircrafts, fleet, flights, partnerships, advertisements, fleet_id Financial Data Function Parameters Return Codes Data getLast10Transactions va_id SUCCESS, NOT FOUND ts, value, reason getNegTransactionSums va_id SUCCESS, NOT FOUND value, reason getPosTransactionSums va_id SUCCESS, NOT FOUND value, reason Flight Data Function Parameters in brackets are optional Return Codes Data getActiveFlights va_id SUCCESS, NOT FOUND departure, arrival, passengers, cargo, user_id, ac_id, flightstate, timestamp, number, lon, lat, pax_economy, pax_business, pax_first getBookedFlights va_id SUCCESS, NOT FOUND departure, arrival, passengers, cargo, user_id, ac_id, number, pax_economy, pax_business, pax_first getFlightReports va_id, (acdb_id), (ac_id), (pilot_id), (days), (count) SUCCESS, NOT FOUND id, dep, arr, pln_arr, ts, pax, ac_type, distance, rating, salary, income, pilot_id, pic, pid, fuel_used, flighttype, hours, ac_id, number, deptime, arrtime, pln_deptime, pln_arrtime, route_id, va_id, va, pax_economy, pax_business, pax_first getReportDetail va_id, report_id SUCCESS, NOT FOUND id, ac_type, ac_id, pic, pilot_id, number, dep, pln_arr, arr, deptime, loc_deptime, arrtime, loc_arrtime, hours, ts, flightstate, rating, ratingreasons, distance, pax, ticket, crew, salary, fuelprice, fuel_bought, fuel_used, profit, version, simrate, multiplier, bonus, cargo, cargo_kg, flighttype, comment, cheat, vs, pax_economy, pax_business, pax_first, ticket_business, ticket_first, fuel_start, fuel_dep, fuel_takeoff, fuel_land, fuel_finish, ticket_factor, interface, simversion, os getRouteData va_id, route_id SUCCESS, NOT FOUND id, va_id, cs_vaid, number, dep, arr, deptime, arrtime, simrate, days, price, state, flighttype, acdb_list, ac_id, remarks, route, limit_pax, limit_cargo getRouteList va_id SUCCESS, NOT FOUND id, number, dep, dep_country, arr, arr_country, deptime, arrtime, simrate, days, price, state, flighttype, acdb_list, ac_id Pilot Data Function Parameters Return Codes Data getPeriodPilotStats va_id, from_ts, to_ts SUCCESS, NOT FOUND id, flights, rating, hours, distance, last, fuel_used, profit, cargo_kg, pax getPilotData va_id, pilot_id SUCCESS, NOT FOUND id, name, surname, user, va_user, rank_id, location, budget, lastactive, active, sigac, timezone, weightunit, language, msgmail, rank, flights, rating, hours, distance, pax, cargo_kg, picture getPilotHours va_id, pilot_id SUCCESS, NOT FOUND id, manufacturer, type, icao, hours getPilotList va_id SUCCESS, NOT FOUND id, name, surname, user, va_user, rank_id, location, last_active, status, budget getPilotRatings va_id, pilot_id SUCCESS, NOT FOUND id, training, manufacturer, type getPilotStats va_id SUCCESS, NOT FOUND id, flights, rating, hours, distance, last, fuel_used, profit, cargo_kg, pax getPilotStatus va_id, pilot_id SUCCESS, NOT FOUND ac_id, route_id, departure, arrival, dep_time, dist, duration, status, lon, lat, flightstate, passengers, income, ticket, timestamp, cargo, multiplier, flighttype Flight Booking Function Parameters Return Codes Data bookFlight va_id, pilot_id, token, route_id, ac_id SUCCESS, NOT FOUND, FLIGHT BOOKED, GROUNDED, SUSPENDED, VA INACTIVE success, message, codeshare, codeshare_msg cancelFlight va_id, pilot_id, token SUCCESS, NOT FOUND result, loss getBookableRoutes va_id, pilot_id SUCCESS, NOT FOUND, FLIGHT BOOKED, GROUNDED, SUSPENDED, VA INACTIVE number, dep, arr, deptime, arrtime, id, state, simrate, flighttype, training, price, list, ac_id getBookableAircraft va_id, pilot_id, route_id SUCCESS, NOT FOUND, FLIGHT BOOKED, GROUNDED, SUSPENDED, VA INACTIVE type, registration, state, id, name, fuel getBookStatus va_id, pilot_id SUCCESS, NOT FOUND status Miscellaneous User Functions Function Parameters Return Codes Data createAccount va_id, givenname, surname, username, email, password, airport, accept_pp SUCCESS, NOT FOUND success, message, code getPilotID va_id, user, token SUCCESS, NOT FOUND id getPrivacyPolicy va_id SUCCESS policy getTransferCost va_id, arr, dep SUCCESS, NOT FOUND cost transferPilot va_id, pilot_id, token, icao SUCCESS, NOT FOUND, INSUFFICIENT FUNDS cost getDistance va_id, icao_from, icao_to SUCCESS, NOT FOUND distance getMetar va_id, icao SUCCESS, NOT FOUND metar Notes <references /> Requested additional functions The following list contains all the functions which were requested by users but aren't implemented yet. Create, edit and delete routes