FaresAPI Documentation

Introduction

We will automatically query all of our airlines for flights that match your search criteria. You will need to save our Flight ID in order to later reference the flights the end customer has selected on your end.

GET Request Parameters

https://faresapi.com/api/v1/flights/get

In order to perform a search you need to provide the following query parameters

from	Mandatory	IATA Code or ID of the Departure airport
to	Mandatory	IATA Code or ID of the Destination airport
departureDate	Mandatory	Departure date in the YYYY-MM-DD format
returnDate	Optional	For return searches, provide a date in the YYYY-MM-DD format
residents[adults]	Mandatory	The number of adults flying, between 0 and 12. Any non-numeric value is ignored. There should be at least one adult regardless of whether they are a resident or a non-resident.
residents[children]	Optional	The number of children flying, between 0 and 12. Any non-numeric value is ignored.
residents[infants]	Optional	The number of infants flying, between 0 and 12. Any non-numeric value is ignored.
nonResidents[adults]	Mandatory	The number of adults flying, between 0 and 12. Any non-numeric value is ignored. There should be at least one adult regardless of whether they are a resident or a non-resident.
nonResidents[children]	Optional	The number of children flying, between 0 and 12. Any non-numeric value is ignored.
nonResidents[infants]	Optional	The number of infants flying, between 0 and 12. Any non-numeric value is ignored.

Searching is done using a simple GET request with query string.
A search is considered one-way if returnDate was not provided and the result will not list any return flights at all (the element is not present in the response).

Please be careful when querying Residents. Residents may get cheaper fares than others. Displaying Resident Fares to Non-Residents will result in poor user experience as upon booking the passenger data is validated against the offer and it may become more expensive if any of the passengers is not eligible.

You can query both Residents and Non-Residents at the same time. Upon redirection, users will see their flights pre-selected and a final price for each flight. They can also access a breakdown, displaying the total price paid by each passenger.

If you are unsure what your passengers' nationalities are and whether they qualify for Resident fares, please only query Non-Residents.

There should be at least one adult regardless of whether they are a resident or a non-resident.
Infants should be no more than Adults.

For ease of use and easier implementation, you can reference Airports via their IATA codes.

Please note that Some Airports may NOT have IATA codes. Those may have fake codes assigned, which may be incompatible and/or inconsistent with yours. If you would like to access ALL airports, mapping yours to ours will be mandatory. In such a case, use IDs and as an added bonus, get better performance.

For better performance, please reference Airports by their IDs if possible.

Response

Each object in the response represents a flight and has the following fields

from An Airport object
- id ID of the airport
- iata IATA code of the airport
- city City name
- country Country name
to An Airport object
- id ID of the airport
- iata IATA code of the airport
- city City name
- country Country name
legs An array of Leg objects
- from An Airport object
  - id ID of the airport
  - iata IATA code of the airport
  - city City name
  - country Country name
- to An Airport object
  - id ID of the airport
  - iata IATA code of the airport
  - city City name
  - country Country name
- number Flight number
- dates An object containing relevant dates
  - departure Departure date
    - date Local Date in the timezone below in the YYYY-MM-DD HH:MM format
    - timezone PHP Timezone, please refer to https://secure.php.net/manual/en/timezones.php for more information.
    - offset timezone offset from GMT in seconds http://php.net/manual/en/datetimezone.getoffset.php for more information.
    - timestamp Unix Timestamp representation of the date. This will likely be your best way to go. Use your most convenient way of parsing dates.
    - iso8601 ISO 8601 Formatted date https://en.wikipedia.org/wiki/ISO_8601 for more information.
    - iso8601 RFC 2822 Formatted date http://www.faqs.org/rfcs/rfc2822.html for more information.
  - arrival Arrival date
    - date Local Date in the timezone below in the YYYY-MM-DD HH:MM format
    - timezone PHP Timezone, please refer to https://secure.php.net/manual/en/timezones.php for more information.
    - offset timezone offset from GMT in seconds http://php.net/manual/en/datetimezone.getoffset.php for more information.
    - timestamp Unix Timestamp representation of the date. This will likely be your best way to go. Use your most convenient way of parsing dates.
    - iso8601 ISO 8601 Formatted date https://en.wikipedia.org/wiki/ISO_8601 for more information.
    - iso8601 RFC 2822 Formatted date http://www.faqs.org/rfcs/rfc2822.html for more information.
- duration Flight duration in seconds and HH:MM format
  - human Flight duration in the HH:MM format, suitable for directly displaying to people
  - seconds Flight duration in seconds
- airline An airline object
  - id The ID of the airline operating the flight
  - name The name of the airline operating the flight
  - twoLetterCode Airline's internationally-recognized two letter code
dates An object containing relevant dates
- departure Departure date
  - date Local Date in the timezone below in the YYYY-MM-DD HH:MM format
  - timezone PHP Timezone, please refer to https://secure.php.net/manual/en/timezones.php for more information.
  - offset timezone offset from GMT in seconds http://php.net/manual/en/datetimezone.getoffset.php for more information.
  - timestamp Unix Timestamp representation of the date. This will likely be your best way to go. Use your most convenient way of parsing dates.
  - iso8601 ISO 8601 Formatted date https://en.wikipedia.org/wiki/ISO_8601 for more information.
  - iso8601 RFC 2822 Formatted date http://www.faqs.org/rfcs/rfc2822.html for more information.
- arrival Arrival date
  - date Local Date in the timezone below in the YYYY-MM-DD HH:MM format
  - timezone PHP Timezone, please refer to https://secure.php.net/manual/en/timezones.php for more information.
  - offset timezone offset from GMT in seconds http://php.net/manual/en/datetimezone.getoffset.php for more information.
  - timestamp Unix Timestamp representation of the date. This will likely be your best way to go. Use your most convenient way of parsing dates.
  - iso8601 ISO 8601 Formatted date https://en.wikipedia.org/wiki/ISO_8601 for more information.
  - iso8601 RFC 2822 Formatted date http://www.faqs.org/rfcs/rfc2822.html for more information.
duration Flight duration in seconds and HH:MM format
- human Flight duration in the HH:MM format, suitable for directly displaying to people
- seconds Flight duration in seconds
airline An airline object
- id The ID of the airline operating the flight
- name The name of the airline operating the flight
- twoLetterCode Airline's internationally-recognized two letter code
price Total Price & Breakdown by residency and passenger type
- currency ISO Currency code
- total Total Price for ALL requested passengers
- residents Price breakdown per passenger type
  - adult Price per Resident Adult with taxes included
  - child Price per Resident Child with taxes included
  - infant Price per Resident Infant with taxes included
- nonResidents Price breakdown per passenger type
  - adult Price per Non-Resident Adult with taxes included
  - child Price per Non-Resident Child with taxes included
  - infant Price per Non-Resident Infant with taxes included
cabinLuggage Total Cabin luggage allowance for all passengers
- amount Amount of luggage allowed in the measure unit below
- unit Measure Unit
  - id Measure unit ID
  - code Measure unit Code - usually KG, but LB and OZ are also supported
  - name Measure unit human-readable name
checkInLuggage Total Check In luggage allowance for all passengers
- amount Amount of luggage allowed in the measure unit below
- unit Measure Unit
  - id Measure unit ID
  - code Measure unit Code - usually KG, but LB and OZ are also supported
  - name Measure unit human-readable name
requiredPassengerFields Required booker data - applies to Create Booking
- phone Phone Code and Phone Number are both required.
- nationality Nationality is required.
- birthDate Birth Date Required.
- birthDateForChildren Birth Date Required - only applies to children.
- birthDateForInfants Birth Date Required - only applies to infants.
- placeOfBirth Place of Birth.
- passport Passport data required. Please refer to Create Booking for reference.
  - number Document Number
  - expiry Document Expiry Date
  - issuer Document Issuing Country
  - issueDate Document Issue Date
- nationalId National ID data required. Please refer to Create Booking for reference.
  - number Document Number
  - expiry Document Expiry Date
  - issuer Document Issuing Country
  - issueDate Document Issue Date
requiredBookerFields Required passenger data - applies to Create Booking
- names First Name, Last Name and Title are all required.
- email Valid Email is required.
- phone Phone Code and Phone Number are both required.
- nationality Nationality is required.
site Site information - where end customers will be redirected upon booking redirection
- id Website ID, makes it easier to collect and build relevant website-related information to present to the customer whilst they are being redirected
- name Website name
- url Website URL
- logo Logo URL that you can programmatically download or serve as a hotlink as new sites are added
instantTicketing Whether tickets will immediately be issued and returned immediately in your successful Issue Booking call, as well as via Get Booking . If false then tickets will follow shortly. You can query every hour or so to update your database with the ticket numbers and PNR Refs.
id Flight ID. You can save this and use it later to either redirect to booking or do a direct booking

Please keep in mind that if you did not request return flights, the return key will be missing.

Receiving a price for a passenger type you did not include in your request is not guaranteed. This means that if you only queried adults, you may or may not get price for children.

The Total Price is the cheapest possible offer generated by our app for the queried passengers based on their residency and passenger types.

A very simple example in PHP (using JSON format): Residents and Non-Residents

$params = array (
  'from' => 1,
  'to' => 2,
  'departureDate' => '2024-12-29',
  'returnDate' => '2025-01-05',
  'affiliate' => 'YourAffiliateCode',
  'secret' => 'YourAffiliateSecret',
  'residents' => 
  array (
    'adults' => 1,
    'children' => 1,
    'infants' => 1,
  ),
  'nonResidents' => 
  array (
    'adults' => 1,
    'children' => 1,
    'infants' => 1,
  ),
);

    // URL
    https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&residents[adults]=1&residents[children]=1&residents[infants]=1&nonResidents[adults]=1&nonResidents[children]=1&nonResidents[infants]=1&_format=json
    // Encoded URL
    https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&residents%5Badults%5D=1&residents%5Bchildren%5D=1&residents%5Binfants%5D=1&nonResidents%5Badults%5D=1&nonResidents%5Bchildren%5D=1&nonResidents%5Binfants%5D=1&_format=json

$queryString = http_build_query($params);
var_dump($queryString);
// from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&residents[adults]=1&residents[children]=1&residents[infants]=1&nonResidents[adults]=1&nonResidents[children]=1&nonResidents[infants]=1

$url = 'https://faresapi.com/api/v1/flights/get?'.$queryString;
var_dump($url);
// https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&residents[adults]=1&residents[children]=1&residents[infants]=1&nonResidents[adults]=1&nonResidents[children]=1&nonResidents[infants]=1

$json = file_get_contents($url);
$data = json_decode($json, true);
var_dump($data);
foreach ($data['departure'] as $flight) {
    // your code to parse and display the flights
}
if (isset($data['return'])) {
    foreach ($data['departure'] as $flight) {
        // your code to parse and display the flights
    }
}

A very simple example in PHP (using JSON format): Residents Only

$params = array (
  'from' => 1,
  'to' => 2,
  'departureDate' => '2024-12-29',
  'returnDate' => '2025-01-05',
  'affiliate' => 'YourAffiliateCode',
  'secret' => 'YourAffiliateSecret',
  'residents' => 
  array (
    'adults' => 1,
    'children' => 1,
    'infants' => 1,
  ),
);

    // URL
    https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&residents[adults]=1&residents[children]=1&residents[infants]=1&_format=json
    // Encoded URL
    https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&residents%5Badults%5D=1&residents%5Bchildren%5D=1&residents%5Binfants%5D=1&_format=json

$queryString = http_build_query($params);
var_dump($queryString);
// from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&residents[adults]=1&residents[children]=1&residents[infants]=1

$url = 'https://faresapi.com/api/v1/flights/get?'.$queryString;
var_dump($url);
// https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&residents[adults]=1&residents[children]=1&residents[infants]=1

$json = file_get_contents($url);
$data = json_decode($json, true);
var_dump($data);
foreach ($data['departure'] as $flight) {
    // your code to parse and display the flights
}
if (isset($data['return'])) {
    foreach ($data['departure'] as $flight) {
        // your code to parse and display the flights
    }
}

A very simple example in PHP (using JSON format): Non-Residents Only

$params = array (
  'from' => 1,
  'to' => 2,
  'departureDate' => '2024-12-29',
  'returnDate' => '2025-01-05',
  'affiliate' => 'YourAffiliateCode',
  'secret' => 'YourAffiliateSecret',
  'nonResidents' => 
  array (
    'adults' => 1,
    'children' => 1,
    'infants' => 1,
  ),
);

    // URL
    https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&nonResidents[adults]=1&nonResidents[children]=1&nonResidents[infants]=1&_format=json
    // Encoded URL
    https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&nonResidents%5Badults%5D=1&nonResidents%5Bchildren%5D=1&nonResidents%5Binfants%5D=1&_format=json

$queryString = http_build_query($params);
var_dump($queryString);
// from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&nonResidents[adults]=1&nonResidents[children]=1&nonResidents[infants]=1

$url = 'https://faresapi.com/api/v1/flights/get?'.$queryString;
var_dump($url);
// https://faresapi.com/api/v1/flights/get?from=1&to=2&departureDate=2024-12-29&returnDate=2025-01-05&affiliate=YourAffiliateCode&secret=YourAffiliateSecret&nonResidents[adults]=1&nonResidents[children]=1&nonResidents[infants]=1

$json = file_get_contents($url);
$data = json_decode($json, true);
var_dump($data);
foreach ($data['departure'] as $flight) {
    // your code to parse and display the flights
}
if (isset($data['return'])) {
    foreach ($data['departure'] as $flight) {
        // your code to parse and display the flights
    }
}