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

Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.