API Documentation

The aviationstack API was built to provide a simple way of accessing global aviation data for real-time and historical flights as well as allow customers to tap into an extensive data set of airline routes and other up-to-date aviation-related information. Requests to the REST API are made using a straightforward HTTP GET URL structure and responses are provided in lightweight JSON format.

The following API documentation can be applied for any major programming langauge and will present general integration guides and explanations around API endpoints, request parameters and response objects. If any questions remain unanswered for you, simply reach out to the aviationstack support team for assistance.

Getting Started

API Access Key & Authentication

After creating an aviationstack account, you will be able to retrieve your unique API access key using your account dashboard. Each aviationstack account can only be assigned one API access key.

To connect to the API, simply attach the access_key parameter to any valid API endpoint URL and set it to your access key. Find an example below, you can click the button on the right side of the code to execute the shown API request.

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/flights
    ? access_key = YOUR_ACCESS_KEY

Keep your key safe: To prevent unauthorized access to your aviationstack account, please make sure to keep your API access key safe at all times. You can always generate a new key using your account dashboard.

256-bit HTTPS Encryption Available on: Basic Plan and higher

Customers registered for the aviationstack Basic Plan or higher may connect to the API using industry-standard 256-bit HTTPS (SSL) encryption. To connect via HTTPS, simply replace the standard http protocol in your API request with https.

Example API Request:

https://api.aviationstack.com

JSONP Callbacks

The aviationstack API supports JSONP Callbacks. To use the JSONP functionality, simply append the callback parameter to your API endpoint URL and set it to a function name of your choice. If a function name is provided, the API will return your API response wrapped inside the tags of the function you specified.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/flights
    ? access_key = YOUR_ACCESS_KEY
    & callback = MY_FUNCTION

Example API Response:

MY_FUNCTION ({
   {
   [...]
   }
})              

Please note: The API also supports Access-Control (CORS) headers.

API Errors

If your request to the aviationstack API does not succeed, the API will return a JSON error response that contains error code and message objects indicating the type of error that occurred. The API also supports HTTP status codes, returning a code of 200 for successful requests, and an error status code (e.g. 404) for failed requests.

If a validation error occurs, hence, an API parameter is used in an invalid way, there will be an additional context object containing multiple sub-objects with the associated API parameter as the key and details about the given validation error(s) further sub-objects. Each instance of a validation error contains key and message objects.

Example Error:

{
   "error": {
      "code": "validation_error",
      "message": "Request failed with validation error",
      "context": {
         "flight_date": [
            {
               "key": "invalid_flight_date",
               "message": "The flight date must be a valid date in the format YYYY-MM-DD."
            }
         ]
      }
   }
}        

Common API Errors:

API Endpoints

Real-Time Flights Available on: All plans

The API is capable of tracking flights and retrieving flight status information in real-time. In order to look up real-time information about one or multiple flights, you can use the API's flights endpoint together with optional parameters to filter your result set.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/flights
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{
    "pagination": {
        "limit": 100,
        "offset": 0,
        "count": 100,
        "total": 1669022
    },
    "data": [
        {
            "flight_date": "2019-12-12",
            "flight_status": "active",
            "departure": {
                "airport": "San Francisco International",
                "timezone": "America/Los_Angeles",
                "iata": "SFO",
                "icao": "KSFO",
                "terminal": "2",
                "gate": "D11",
                "delay": 13,
                "scheduled": "2019-12-12T04:20:00+00:00",
                "estimated": "2019-12-12T04:20:00+00:00",
                "actual": "2019-12-12T04:20:13+00:00",
                "estimated_runway": "2019-12-12T04:20:13+00:00",
                "actual_runway": "2019-12-12T04:20:13+00:00"
            },
            "arrival": {
                "airport": "Dallas/Fort Worth International",
                "timezone": "America/Chicago",
                "iata": "DFW",
                "icao": "KDFW",
                "terminal": "A",
                "gate": "A22",
                "baggage": "A17",
                "delay": 0,
                "scheduled": "2019-12-12T04:20:00+00:00",
                "estimated": "2019-12-12T04:20:00+00:00",
                "actual": null,
                "estimated_runway": null,
                "actual_runway": null
            },
            "airline": {
                "name": "American Airlines",
                "iata": "AA",
                "icao": "AAL"
            },
            "flight": {
                "number": "1004",
                "iata": "AA1004",
                "icao": "AAL1004",
                "codeshared": null
            },
            "aircraft": {
               "registration": "N160AN",
               "iata": "A321",
               "icao": "A321",
               "icao24": "A0F1BB"
            },
            "live": {
                "updated": "2019-12-12T10:00:00+00:00",
                "latitude": 36.28560000,
                "longitude": -106.80700000,
                "altitude": 8846.820,
                "direction": 114.340,
                "speed_horizontal": 894.348,
                "speed_vertical": 1.188,
                "is_ground": false
            }
        }, 
        [...]
    ]
}

Please note: The API response above has been shortened to show only one flight result for readability purposes.

API Response Objects:

Historical Flights Available on: Basic Plan and higher

Apart from providing data about real-time flight, the API's flights endpoint is also capable of looking up data about historical flights. In order to request data about one or more past flights, simply attach the flight_date parameter to your API request URL and set it to a date of your choice.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/flights
    ? access_key = YOUR_ACCESS_KEY
    & flight_date = 2019-12-11

HTTP GET Request Parameters:

Example API Response:

Important: The API response returned for historical flights is identical to the API response returned for real-time flight data. To see the API response, please jump to the Real-Time Flights section.

Airline Routes Available on: Basic Plan and higher

The aviationstack API is capable of providing data about airline routes, updated every 24 hours. In order to get airline route data, use the API's routes endpoint along with a series of optional parameters to filter results.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/routes
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 208033
   },
   "data": [
      {
         "departure": {
            "airport": "Brussels Airport",
            "timezone": "Europe/Brussels",
            "iata": "BRU",
            "icao": "EBBR",
            "terminal": null,
            "time": "06:10:00"
         },
         "arrival": {
            "airport": "Girona-Costa Brava",
            "timezone": "Europe/Madrid",
            "iata": "GRO",
            "icao": "LEGE",
            "terminal": "1",
            "time": "07:55:00"
         },
         "airline": {
            "name": "Brussels Airlines",
            "callsign": "B-LINE",
            "iata": "SN",
            "icao": "BEL"
         },
         "flight": {
            "number": "3683"
         }
      },
      [...]
   ]
}

Please note: The API response above has been shortened to show only one flight result for readability purposes.

API Response Objects:

Airports Available on: All plans

To get data about global airports, you can use the API's airports endpoint. Customers subscribed to the Basic Plan or higher may also make use of the search request parameter to get airport autocomplete suggestions.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/airports
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 6471
   },
   "data": [
      {
         "airport_name": "Anaa",
         "iata_code": "AAA",
         "icao_code": "NTGA",
         "latitude": "-17.05",
         "longitude": "-145.41667",
         "geoname_id": "6947726",
         "timezone": "Pacific/Tahiti",
         "gmt": "-10",
         "phone_number": null,
         "country_name": "French Polynesia",
         "country_iso2": "PF",
         "city_iata_code": "AAA"
      },
      [...]
   ]
}

Please note: The API response above has been shortened to show only one airport result for readability purposes.

API Response Objects:

Airlines Available on: All plans

To get data about global airlines, you can use the API's airlines endpoint. Customers subscribed to the Basic Plan or higher may also make use of the search request parameter to get airline autocomplete suggestions.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/airlines
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 13131
   },
   "data": [
      {
         "airline_name": "American Airlines",
         "iata_code": "AA",
         "iata_prefix_accounting": "1",
         "icao_code": "AAL",
         "callsign": "AMERICAN",
         "type": "scheduled",
         "status": "active",
         "fleet_size": "963",
         "fleet_average_age": "10.9",
         "date_founded": "1934",
         "hub_code": "DFW",
         "country_name": "United States",
         "country_iso2": "US"
      },
      [...]
   ]
}

Please note: The API response above has been shortened to show only one airline result for readability purposes.

API Response Objects:

Airplanes Available on: All plans

To get data about different airplanes/aircrafts, you can use the API's airplanes endpoint. Customers subscribed to the Basic Plan or higher may also make use of the search request parameter to get airplane autocomplete suggestions.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/airplanes
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 19052
   },
   "data": [
      {
         "registration_number": "YR-BAC",
         "production_line": "Boeing 737 Classic",
         "iata_type": "B737-300",
         "model_name": "737",
         "model_code": "B737-377",
         "icao_code_hex": "4A0823",
         "iata_code_short": "B733",
         "construction_number": "23653",
         "test_registration_number": null,
         "rollout_date": null,
         "first_flight_date": "1986-08-02T22:00:00.000Z",
         "delivery_date": "1986-08-21T22:00:00.000Z",
         "registration_date": "0000-00-00",
         "line_number": "1260",
         "plane_series": "377",
         "airline_iata_code": "0B",
         "airline_icao_code": null,
         "plane_owner": "Airwork Flight Operations Ltd",
         "engines_count": "2",
         "engines_type": "JET",
         "plane_age": "31",
         "plane_status": "active",
         "plane_class": null
      },
      [...]
   ]
}

Please note: The API response above has been shortened to show only one airplane result for readability purposes.

API Response Objects:

Aircraft Types Available on: All plans

To get data about different aircraft types, you can use the API's aircraft_types endpoint. Customers subscribed to the Basic Plan or higher may also make use of the search request parameter to get aircraft type autocomplete suggestions.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/aircraft_types
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 310
   },
   "data": [
      {
         "aircraft_name": "Fokker 100",
         "iata_code": "100"
      },
      [...]
   ]
}

Please note: The API response above has been shortened to show only one aircraft type result for readability purposes.

API Response Objects:

Aviation Taxes Available on: All plans

To get data about aviation taxes, you can use the API's taxes endpoint. Customers subscribed to the Basic Plan or higher may also make use of the search request parameter to get aircraft type autocomplete suggestions.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/taxes
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 521
   },
   "data": [
      {
         "tax_name": "Government Tax",
         "iata_code": "AB"
      },
      [...]
   ]
}

Please note: The API response above has been shortened to show only one aviation tax result for readability purposes.

API Response Objects:

Cities Available on: All plans

To look up destination cities, you can use the API's cities endpoint. Customers subscribed to the Basic Plan or higher may also make use of the search request parameter to get city autocomplete suggestions.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/cities
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{    
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 9368
   },
   "data": [
      {
         "city_name": "Anaa",
         "iata_code": "AAA",
         "country_iso2": "PF",
         "latitude": "-17.05",
         "longitude": "-145.41667",
         "timezone": "Pacific/Tahiti",
         "gmt": "-10",
         "geoname_id": "0"
      },
      [...]
   ]
}

Please note: The API response above has been shortened to show only one city result for readability purposes.

API Response Objects:

Countries Available on: All plans

To look up destination countries, you can use the API's countries endpoint. Customers subscribed to the Basic Plan or higher may also make use of the search request parameter to get country autocomplete suggestions.

Example API Request:

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/countries
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Example API Response:

{
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 252
   },
   "data": [
      {
         "country_name": "Andorra",
         "country_iso2": "AD",
         "country_iso3": "AND",
         "country_iso_numeric": "20",
         "population": "84000",
         "capital": "Andorra la Vella",
         "continent": "EU",
         "currency_name": "Euro",
         "currency_code": "EUR",
         "fips_code": "AN",
         "phone_prefix": "376"
      },
      [...]
   ]
}      

Please note: The API response above has been shortened to show only one country result for readability purposes.

API Response Objects:

Autocomplete Available on: Basic Plan and higher

As outlined for some API endpoints, the aviationstack API is capable of providing result suggestions based on a search term that can be used for autocomplete features in your application. To get autocomplete suggestions, simply attach the search parameter to the API request URL of any supported API endpoint and set it to a search term of your choice.

Supported API Endpoints:

• Airports Endpoint: /airports
• Airlines Endpoint: /airlines
• Airplanes Endpoint: /airplanes
• Aircraft Types Endpoint: /aircraft_types
• Aviation Tax Endpoint: /taxes
• Cities Endpoint: /cities
• Countries Endpoint: /countries

Example API Request: In the following example we search for suggestions for airlines based on the term "american".

Sign Up to Run API Requesthttps://api.aviationstack.com/v1/airlines
    ? access_key = YOUR_ACCESS_KEY
    & search = american

Example API Response:

{
   "pagination": {
       "limit": 100,
       "offset": 0,
       "count": 100,
       "total": 1
   },
   "data": [
      {
         "airline_name": "American Airlines",
         "iata_code": "AA",
         "iata_prefix_accounting": "1",
         "icao_code": "AAL",
         "callsign": "AMERICAN",
         "type": "scheduled",
         "status": "active",
         "fleet_size": "963",
         "fleet_average_age": "10.9",
         "date_founded": "1934",
         "hub_code": "DFW",
         "country_name": "United States",
         "country_iso2": "US"
      },
      [...]
   ]
}

Please note: The API response above has been shortened to show only one country result for readability purposes. To learn more about API response objects of this particular API endpoint, please jump to the Airlines API endpoint.

Code Examples

A number of code examples in different programming languages were prepared for you to get up and running with the aviationstack API as quickly as possible. You will find them below in PHP, Python, Node.js., jQuery, Go and Ruby.

Code Example - PHP

$queryString = http_build_query([
  'access_key' => 'YOUR_ACCESS_KEY'
]);

$ch = curl_init(sprintf('%s?%s', 'https://api.aviationstack.com/v1/flights', $queryString));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$json = curl_exec($ch);
curl_close($ch);

$api_result = json_decode($json, true);

foreach ($api_result['results'] as $flight) {
    if (!$flight['live']['is_ground']) {
        echo sprintf("%s flight %s from %s (%s) to %s (%s) is in the air.",
            $flight['airline']['name'],
            $flight['flight']['iata'],
            $flight['departure']['airport'],
            $flight['departure']['iata'],
            $flight['arrival']['airport'],
            $flight['arrival']['iata']
            ), PHP_EOL;
    }
}

Code Example - Python

import requests

params = {
  'access_key': 'YOUR_ACCESS_KEY'
}

api_result = requests.get('https://api.aviationstack.com/v1/flights', params)

api_response = api_result.json()

for flight in api_response['results']:
    if (flight['live']['is_ground'] is False):
        print(u'%s flight %s from %s (%s) to %s (%s) is in the air.' % (
            flight['airline']['name'],
            flight['flight']['iata'],
            flight['departure']['airport'],
            flight['departure']['iata'],
            flight['arrival']['airport'],
            flight['arrival']['iata']))

Code Example - Nodejs

const axios = require('axios');
const params = {
  access_key: 'YOUR_ACCESS_KEY'
}

axios.get('https://api.aviationstack.com/v1/flights', {params})
  .then(response => {
    const apiResponse = response.data;
    if (Array.isArray(apiResponse['results'])) {
        apiResponse['results'].forEach(flight => {
            if (!flight['live']['is_ground']) {
                console.log(`${flight['airline']['name']} flight ${flight['flight']['iata']}`,
                    `from ${flight['departure']['airport']} (${flight['departure']['iata']})`,
                    `to ${flight['arrival']['airport']} (${flight['arrival']['iata']}) is in the air.`);
            }
        });
    }
  }).catch(error => {
    console.log(error);
  });

Code Example - jQuery

$.ajax({
  url: 'https://api.aviationstack.com/v1/flights',
  data: {
    access_key: 'YOUR_ACCESS_KEY'
  },
  dataType: 'json',
  success: function(apiResponse) {
    if (Array.isArray(apiResponse['results'])) {
      apiResponse['results'].forEach(flight => {
        if (!flight['live']['is_ground']) {
          console.log(`${flight['airline']['name']} flight ${flight['flight']['iata']}`,
              `from ${flight['departure']['airport']} (${flight['departure']['iata']})`,
              `to ${flight['arrival']['airport']} (${flight['arrival']['iata']}) is in the air.`);
        }
      });
    }
  }
});

Code Example - Go

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
)

type Airline struct {
  Name string `json:"name"`
}

type FlightInfo struct {
  IATACode string `json:"iata"`
}

type Destination struct {
  Airport string `json:"airport"`
  IATACode string `json:"iata"`
}

type LiveData struct {
  IsGround bool `json:"is_ground"`
}

type Flight struct {
    Airline Airline `json:"airline"`
    FlightInfo FlightInfo `json:"flight"`
    Departure Destination `json:"departure"`
    Arrival Destination `json:"arrival"`
    Live LiveData `json:"live"`
}

type Response struct {
	Flights []Flight `json:"results"`
}

func main() {
  httpClient := http.Client{}

  req, err := http.NewRequest("GET", "https://api.aviationstack.com/v1/flights", nil)
  if err != nil {
    panic(err)
  }

  q := req.URL.Query()
  q.Add("access_key", "YOUR_ACCESS_KEY")
  req.URL.RawQuery = q.Encode()

  res, err := httpClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  var apiResponse Response
  json.NewDecoder(res.Body).Decode(&apiResponse)

  for _, flight := range apiResponse.Flights {
    if (!flight.Live.IsGround) {
        fmt.Println(fmt.Sprintf("%s flight %s from %s (%s) to %s (%s) is in the air.",
            flight.Airline.Name,
            flight.FlightInfo.IATACode,
            flight.Departure.Airport,
            flight.Departure.IATACode,
            flight.Arrival.Airport,
            flight.Arrival.IATACode))
    }
  }
}

Code Example - Ruby

require 'net/http'
require 'json'

params = {
  :access_key => "YOUR_ACCESS_KEY"
}
uri = URI('https://api.aviationstack.com/v1/flights')
uri.query = URI.encode_www_form(params)
json = Net::HTTP.get(uri)
api_response = JSON.parse(json)

for flight in api_response['results']
    unless flight['live']['is_ground']
        puts sprintf("%s flight %s from %s (%s) to %s (%s) is in the air.",
            flight['airline']['name'],
            flight['flight']['iata'],
            flight['departure']['airport'],
            flight['departure']['iata'],
            flight['arrival']['airport'],
            flight['arrival']['iata']
        )
    end
end