Quickstart Guide

In a rush or not interested in reading documentation? There is a short 3-Step Quickstart Guide you can use to started right away.

Code Examples

To get you up and running quickly, we have prepared code examples in a series of programming languages. Click below to explore.

Code Examples

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.

https://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:

https://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:

Code Type Description
401 invalid_access_key An invalid API access key was supplied.
401 missing_access_key No API access key was supplied.
401 inactive_user The given user account is inactive.
403 https_access_restricted HTTPS access is not supported on the current subscription plan.
403 function_access_restricted The given API endpoint is not supported on the current subscription plan.
404 invalid_api_function The given API endpoint does not exist.
404 404_not_found Resource not found.
429 usage_limit_reached The given user account has reached its monthly allowed request volume.
429 rate_limit_reached The given user account has reached the rate limit.
500 internal_error An internal error occurred.

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:

https://api.aviationstack.com/v1/flights
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
flight_status [Optional] Filter your results by flight status. Available values: scheduled, active, landed, cancelled, incident, diverted
flight_date [Optional] Filter your results by providing a flight date in the format YYYY-MM-DD. Example: 2019-02-31
dep_iata [Optional] Filter your results by departure city or airport using an IATA code. You can retrieve IATA codes using the Airports or Cities API endpoints.
arr_iata [Optional] Filter your results by arrival city or airport using an IATA code. You can retrieve IATA codes using the Airports or Cities API endpoints.
dep_icao [Optional] Filter your results by departure airport using an ICAO code. You can retrieve ICAO codes using the Airports API endpoint.
arr_icao [Optional] Filter your results by arrival airport using an ICAO code. You can retrieve ICAO codes using the Airports API endpoint.
airline_name [Optional] Filter your results by airline name. You can retrieve airline names using the Airlines API endpoint.
airline_iata [Optional] Filter your results by airline IATA code. You can retrieve airline IATA codes using the Airlines API endpoint.
airline_icao [Optional] Filter your results by airline ICAO code. You can retrieve airline ICAO codes using the Airlines API endpoint.
flight_number [Optional] Filter your results by providing a flight number. Example: 2557
flight_iata [Optional] Filter your results by providing a flight IATA code. Example: MU2557
flight_icao [Optional] Filter your results by providing a flight ICAO code. Example: CES2557
min_delay_dep [Optional] Filter your results by providing a minimum amount of minutes in departure delay. Example: 7 for seven minutes of delay in departure.
min_delay_arr [Optional] Filter your results by providing a minimum amount of minutes in arrival delay. Example: 7 for seven minutes of delay in arrival.
max_delay_dep [Optional] Filter your results by providing a maximum amount of minutes in departure delay. Example: 60 for one hour of delay in departure.
max_delay_arr [Optional] Filter your results by providing a maximum amount of minutes in arrival delay. Example: 60 for one hour of delay in arrival.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of flights, included objects are explained below.
flight_date Returns the date of the flight. Format: YYYY-MM-DD
flight_status Returns the flight status. Possible values: scheduled, active, landed, cancelled, incident, diverted
departure > airport Returns the name of the departure airport.
departure > timezone Returns the departure timezone. Example: America/Los_Angeles
departure > iata Returns the IATA code of the departure location/airport.
departure > icao Returns the ICAO code of the departure location/airport.
departure > terminal Returns the departure terminal.
departure > gate Returns the departure gate.
departure > delay Returns the delay in departure in minutes.
departure > scheduled Returns the scheduled departure date and time in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
departure > estimated Returns the estimated departure date and time in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
departure > actual Returns the actual departure date and time in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
departure > estimated_runway Returns the estimated runway date and time in RFC3339 (ISO8601) format in the departure location/airport. Example: 2019-12-12T04:20:00+00:00
departure > actual_runway Returns the actual runway date and time in the departure location/airport in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
arrival > airport Returns the name of the arrival airport.
arrival > timezone Returns the arrival timezone. Example: America/Los_Angeles
arrival > iata Returns the IATA code of the arrival location/airport.
arrival > icao Returns the ICAO code of the arrival location/airport.
arrival > terminal Returns the arrival terminal.
arrival > gate Returns the arrival gate.
arrival > baggage Returns the baggage claim gate at the arrival airport.
arrival > delay Returns the delay in arrival in minutes.
arrival > scheduled Returns the scheduled arrival date and time in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
arrival > estimated Returns the actual arrival date and time in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
arrival > actual Returns the actual arrival date and time in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
arrival > estimated_runway Returns the estimated runway date and time in the arrival location/airport in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
arrival > actual_runway Returns the actual runway date and time in the arrival location/airport in RFC3339 (ISO8601) format. Example: 2019-12-12T04:20:00+00:00
airline > name Returns the name of the airline. Example: American Airlines
airline > iata Returns the IATA code of the airline. Example: AA
airline > icao Returns the ICAO code of the airline. Example: AAL
flight > number Returns the flight number. Example: 1004
flight > iata Returns the IATA number of the flight. Example: AA1004
flight > icao Returns the ICAO number of the flight. Example: AAL1004
flight > codeshared Returns one or multiple sub-objects containing details about other flights and airlines participating in a codeshare agreement associated with the current flight.
live > updated Returns the exact date and time the live data was collected in RFC3339 (ISO8601) format.
live > latitude Returns the latitude coordinate associated with the aircraft location.
live > longitude Returns the longitude coordinate associated with the aircraft location.
live > altitude Returns the altitude (in meters) of the aircraft at the given time.
live > direction Returns the direction (in degrees) of the aircraft at the given time.
live > speed_horizontal Returns the horizontal speed (in kilometers per hour) of the aircraft at the given time.
live > speed_vertical Returns the vertical speed (in kilometers per hour) of the aircraft at the given time.
live > is_ground Returns true or false depending on whether or not the aircraft is on the ground at the given time.
live > aircraft > registration Returns the registration number of the aircraft. Example: N160AN
live > aircraft > iata Returns the IATA code of the aircraft. Example: A321
live > aircraft > icao Returns the ICAO code of the aircraft. Example: A321
live > aircraft > icao24 Returns the ICAO24 code of the aircraft. Example: A0F1BB

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:

https://api.aviationstack.com/v1/flights
    ? access_key = YOUR_ACCESS_KEY
    & flight_date = 2019-12-11

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
flight_date [Required] Specify your historical flight date in the format YYYY-MM-DD. Example: 2019-02-31
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
flight_status [Optional] Filter your results by flight status. Available values: scheduled, active, landed, cancelled, incident, diverted
dep_iata [Optional] Filter your results by departure city or airport using an IATA code. You can retrieve IATA codes using the Airports or Cities API endpoints.
arr_iata [Optional] Filter your results by arrival city or airport using an IATA code. You can retrieve IATA codes using the Airports or Cities API endpoints.
dep_icao [Optional] Filter your results by departure airport using an ICAO code. You can retrieve ICAO codes using the Airports API endpoint.
arr_icao [Optional] Filter your results by arrival airport using an ICAO code. You can retrieve ICAO codes using the Airports API endpoint.
airline_name [Optional] Filter your results by airline name. You can retrieve airline names using the Airlines API endpoint.
airline_iata [Optional] Filter your results by airline IATA code. You can retrieve airline IATA codes using the Airlines API endpoint.
airline_icao [Optional] Filter your results by airline ICAO code. You can retrieve airline ICAO codes using the Airlines API endpoint.
flight_number [Optional] Filter your results by providing a flight number. Example: 2557
flight_iata [Optional] Filter your results by providing a flight IATA code. Example: MU2557
flight_icao [Optional] Filter your results by providing a flight ICAO code. Example: CES2557
min_delay_dep [Optional] Filter your results by providing a minimum amount of minutes in departure delay. Example: 7 for seven minutes of delay in departure.
min_delay_arr [Optional] Filter your results by providing a minimum amount of minutes in arrival delay. Example: 7 for seven minutes of delay in arrival.
max_delay_dep [Optional] Filter your results by providing a maximum amount of minutes in departure delay. Example: 60 for one hour of delay in departure.
max_delay_arr [Optional] Filter your results by providing a maximum amount of minutes in arrival delay. Example: 60 for one hour of delay in arrival.

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:

https://api.aviationstack.com/v1/routes
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
flight_number [Optional] Filter your results by providing a flight number. Example: 2557
dep_iata [Optional] Filter your results by departure city or airport using an IATA code. You can retrieve IATA codes using the Airports or Cities API endpoints.
arr_iata [Optional] Filter your results by arrival city or airport using an IATA code. You can retrieve IATA codes using the Airports or Cities API endpoints.
dep_icao [Optional] Filter your results by departure airport using an ICAO code. You can retrieve ICAO codes using the Airports API endpoint.
arr_icao [Optional] Filter your results by arrival airport using an ICAO code. You can retrieve ICAO codes using the Airports API endpoint.
airline_iata [Optional] Filter your results by airline IATA code. You can retrieve airline IATA codes using the Airlines API endpoint.
airline_icao [Optional] Filter your results by airline ICAO code. You can retrieve airline ICAO codes using the Airlines API endpoint.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of flights, included objects are explained below.
departure > airport Returns the name of the departure airport.
departure > timezone Returns the departure timezone. Example: America/Los_Angeles
departure > iata Returns the IATA code of the departure location/airport.
departure > icao Returns the ICAO code of the departure location/airport.
departure > terminal Returns the departure terminal.
departure > time Returns the departure time.
arrival > airport Returns the name of the arrival airport.
arrival > timezone Returns the arrival timezone. Example: America/Los_Angeles
arrival > iata Returns the IATA code of the arrival location/airport.
arrival > icao Returns the ICAO code of the arrival location/airport.
arrival > terminal Returns the arrival terminal.
arrival > time Returns the departure time.
airline > name Returns the name of the airline. Example: American Airlines
airline > callsign Returns the ICAO callsign of the airline.
airline > iata Returns the IATA code of the airline. Example: AA
airline > icao Returns the ICAO code of the airline. Example: AAL
flight > number Returns the flight number. Example: 1004

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:

https://api.aviationstack.com/v1/airports
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
search [Optional] Use this parameter to get autocomplete suggestions for airports by specifying any search term as a string. This feature is only available on the Basic Plan and higher.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of results, included objects are explained below.
airport_name Returns the full name of the airport.
iata_code Returns the IATA code associated with the airport.
icao_code Returns the ICAO code associated with the airport.
latitude Returns the latitude coordinate associated with the airport location.
longitude Returns the longitude coordinate associated with the airport location.
geoname_id Returns the GeoNames ID of the airport.
timezone Returns the timezone the airport is in. Example: America/Los_Angeles
gmt Returns the GMT offset in hours.
phone_number Returns the phone number of the airport.
country_name Returns the name of the country the airport is in.
country_iso2 Returns the ISO code of the country the airport is in.
city_iata_code Returns the IATA code of the city the airport is in.

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:

https://api.aviationstack.com/v1/airlines
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
search [Optional] Use this parameter to get autocomplete suggestions for airlines by specifying any search term as a string. This feature is only available on the Basic Plan and higher.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of results, included objects are explained below.
airline_name Returns the full name of the airline.
iata_code Returns the IATA code of the airline.
iata_prefix_accounting Returns the IATA prefix or accounting code of the airline.
icao_code Returns the ICAO code of the airline.
callsign Returns the ICAO callsign of the airline.
type Returns the type of airline.
status Returns the current status of the airline.
fleet_size Returns the fleet size of the airline.
fleet_average_age Returns the average aircraft age of the fleet.
date_founded Returns the founding year of the airline.
hub_code Returns the hub code associated with the airline.
country_name Returns the name of the origin country of the airline.
country_iso2 Returns the 2-letter ISO code of the origin country of the airline.

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:

https://api.aviationstack.com/v1/airplanes
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
search [Optional] Use this parameter to get autocomplete suggestions for airplanes by specifying any search term as a string. This feature is only available on the Basic Plan and higher.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of results, included objects are explained below.
registration_number Returns the registration number of the airplane.
production_line Returns the production line identifier of the airplane.
iata_type Returns the IATA type of the airplane.
model_name Returns the model name of the airplane.
model_code Returns the model code of the airplane.
icao_code_hex Returns the HEX ICAO code of the airplane.
iata_code_short Returns the short IATA code of the airplane.
construction_number Returns the construction number of the airplane.
test_registration_number Returns the test registration number of the airplane.
rollout_date Returns the rollout date of the airplane.
first_flight_date Returns the first flight date of the airplane.
delivery_date Returns the initial delivery date of the airplane.
registration_date Returns the initial registration date of the airplane.
line_number Returns the production line number of the airplane.
plane_series Returns the airplane series.
airline_iata_code Returns the IATA code of the airplane.
airline_icao_code Returns the ICAO code of the airplane.
plane_owner Returns the owner name of the airplane.
engines_count Returns the number of engines on the airplane.
engines_type Returns the type of engines on the airplane.
plane_age Returns the age of the airplane in years.
plane_status Returns the current status of the airplane.
plane_class Returns one or multiple sub-objects containing information about the types of classes (e.g. Economy Class, Business Class) are available ont the given airplane as well as details about the number of seats available, beds, cabin width, and more.

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:

https://api.aviationstack.com/v1/aircraft_types
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
search [Optional] Use this parameter to get autocomplete suggestions for aircraft types by specifying any search term as a string. This feature is only available on the Basic Plan and higher.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of results, included objects are explained below.
aircraft_name Returns the aircraft name associated with the aircraft type.
iata_code Returns the IATA code associated with the aircraft type.

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:

https://api.aviationstack.com/v1/taxes
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
search [Optional] Use this parameter to get autocomplete suggestions for aviation taxes by specifying any search term as a string. This feature is only available on the Basic Plan and higher.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of results, included objects are explained below.
tax_name Returns the name of the aviation tax.
iata_code Returns the IATA code associated with the aviation tax.

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:

https://api.aviationstack.com/v1/cities
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
search [Optional] Use this parameter to get autocomplete suggestions for cities by specifying any search term as a string. This feature is only available on the Basic Plan and higher.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of results, included objects are explained below.
city_name Returns the name of the city.
iata_code Returns the IATA code of the city.
country_iso2 Returns the 2-letter ISO code of the city.
latitude Returns the latitude coordinate associated with the city.
longitude Returns the longitude coordinate associated with the city.
timezone Returns the timezone the city is in.
gmt Returns the GMT offset in hours.
geoname_id Returns the GeoName ID associated with the city.

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:

https://api.aviationstack.com/v1/countries
    ? access_key = YOUR_ACCESS_KEY

HTTP GET Request Parameters:

Object Description
access_key [Required] Your API access key, which can be found in your acccount dashboard.
callback [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks.
limit [Optional] Specify a limit of results to return in your API response. Maximum allowed value is 100 below Professional Plan and 1000 on and above Professional Plan. Default value is 100.
offset [Optional] Specify an offset for pagination. Example: Specifying an offset of 10 in combination with a limit of 10 will show results 10-20. Default offset value is 0, starting with the first available result.
search [Optional] Use this parameter to get autocomplete suggestions for countries by specifying any search term as a string. This feature is only available on the Basic Plan and higher.

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:

Response Object Description
pagination > limit Returns the specified or default limit of results per pagination page.
pagination > offset Returns the specified or default pagination offset.
pagination > count Returns the number of results found on the current pagination page.
pagination > total Returns the total number of results found for your API request.
results Returns an array of results, included objects are explained below.
country_name Returns the name of the country.
country_iso2 Returns the 2-letter ISO code of the country.
country_iso3 Returns the 3-letter ISO code of the country.
country_iso_numeric Returns the numeric ISO code of the country.
population Returns the population of the country.
capital Returns the capital of the country.
continent Returns the continent the country is located in.
currency_name Returns the name of the currency associated with the country.
currency_code Returns the code of the currency associated with the country.
fips_code Returns the FIPS code of the country.
phone_prefix Returns the phone prefix associated with the country.

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".

https://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

Read enough? Get started now by registering for a free API key!

Get Free API Key