SITA Airport Reference API

SITA Advanced Data Services
dots.support@sita.aero
version 1.4.0-SNAPSHOT

Table of Contents

1 Revision History
2 Registration and API Signup
- 2.1 API Key Usage
- 2.2 Security
3 SITA Airport Reference API
- 3.1 Resources
- 3.2 Airport V3 (Current)
4 Error Response
- 4.1 Response fields
- 4.2 HTTP Response
5 Appendix A - Airport Reference Use Cases

1 Revision History

Date	Version	Description	Author
`27 October 2022`	`1.0`	`Initial documentation creation`	`L Kenny`

2 Registration and API Signup

To access the APIs you will need to be issued an api key. These values are passed in as an HTTP header (or optionally query parameter).

2.1 API Key Usage

The API authentication key will be passed in an HTTP header as follows:

name of header: X-apiKey
value of header: The api key as generated for the application.

2.2 Security

All incoming requests will be REST over HTTPS. Users are authenticated using their registration (api) key.

3 SITA Airport Reference API

The SITA Airport Reference API is a REST based service which provides information about Airports around the world.

This section describes each SITA Airport Reference API service. Detailed API structure, example requests and responses, JSON schema for request (where appropriate) and responses, and error response codes and formats are included.

3.2 Airport V3 (Current)

3.2.1 Get Airports by Name or Code

Path parameters

/v3/airports/match/{airportNamePartial}
Parameter	Description
`airportNamePartial`	Text that will be matched against IATA or ICAO code, the city name and the airport name.

Request headers

Name	Description
`Content-Type`	The Content-Type of this request.
`X-apiKey`	The Authorization header that contains the Api Key.

Response fields

Path	Type	Description
`airports[].icaoCode`	`String`	Airport ICAO code
`airports[].ident`	`String`	Airport SITA identifier
`airports[].city`	`String`	City code where Airport is located
`airports[]`	`Array`	Airport records returned
`airports[].name`	`String`	Airport name
`airports[].latitude`	`Number`	Airports Latitude position
`airports[].elevation`	`Number`	Airport altitude
`airports[].longitude`	`Number`	Airports Longitude position
`airports[].type`	`String`	Airport Type
`airports[].country`	`String`	Country Name where Airport is located
`airports[].countryCode`	`String`	Country Code where Airport is located
`airports[].timezone`	`String`	Airports Timezone
`airports[].continent`	`String`	Continent where Airport is located
`success`	`Boolean`	Indicates if request was correctly processed
`airports[].localCode`	`String`	Local airport code
`airports[].iataCode`	`String`	Airport IATA code
`airports[].region`	`String`	Region code where Airport is located

Curl request

$ curl 'https://data-qa.api.aero/v3/airports/match/GVA' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-apiKey: apikey_xyz'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 884

{
  "success" : true,
  "airports" : [ {
    "ident" : "UKFG",
    "type" : "AIRPORT",
    "elevation" : 721,
    "continent" : "EU",
    "countryCode" : "UA",
    "region" : "UA-43",
    "localCode" : "",
    "name" : "Gvardeyskoe Air Base",
    "iataCode" : "",
    "icaoCode" : "UKFG",
    "city" : "Sarabuz",
    "latitude" : 45.1150016784668,
    "longitude" : 33.97700119018555,
    "country" : "",
    "timezone" : ""
  }, {
    "ident" : "LSGG",
    "type" : "LARGE_AIRPORT",
    "elevation" : 1411,
    "continent" : "EU",
    "countryCode" : "CH",
    "region" : "CH-GE",
    "localCode" : "",
    "name" : "Geneva Cointrin International Airport",
    "iataCode" : "GVA",
    "icaoCode" : "LSGG",
    "city" : "Geneva",
    "latitude" : 45.1150016784668,
    "longitude" : 33.97700119018555,
    "country" : "",
    "timezone" : ""
  } ]
}

3.2.2 Get Airport by Code

Request headers

Name	Description
`Content-Type`	The Content-Type of this request.
`X-apiKey`	The Authorization header that contains the Api Key.

Response fields

Path	Type	Description
`airports[].icaoCode`	`String`	Airport ICAO code
`airports[].ident`	`String`	Airport SITA identifier
`airports[].city`	`String`	City code where Airport is located
`airports[]`	`Array`	Airport records returned
`airports[].name`	`String`	Airport name
`airports[].latitude`	`Number`	Airports Latitude position
`airports[].elevation`	`Number`	Airport altitude
`airports[].longitude`	`Number`	Airports Longitude position
`airports[].type`	`String`	Airport Type
`airports[].country`	`String`	Country Name where Airport is located
`airports[].countryCode`	`String`	Country Code where Airport is located
`airports[].timezone`	`String`	Airports Timezone
`airports[].continent`	`String`	Continent where Airport is located
`success`	`Boolean`	Indicates if request was correctly processed
`airports[].localCode`	`String`	Local airport code
`airports[].iataCode`	`String`	Airport IATA code
`airports[].region`	`String`	Region code where Airport is located

Curl request

$ curl 'https://data-qa.api.aero/v3/airports/GVA' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-apiKey: apikey_xyz'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 477

{
  "success" : true,
  "airports" : [ {
    "ident" : "LSGG",
    "type" : "LARGE_AIRPORT",
    "elevation" : 1411,
    "continent" : "EU",
    "countryCode" : "CH",
    "region" : "CH-GE",
    "localCode" : "",
    "name" : "Geneva Cointrin International Airport",
    "iataCode" : "GVA",
    "icaoCode" : "LSGG",
    "city" : "Geneva",
    "latitude" : 45.1150016784668,
    "longitude" : 33.97700119018555,
    "country" : "",
    "timezone" : ""
  } ]
}

3.2.3 Get All Airports

Request headers

Name	Description
`Content-Type`	The Content-Type of this request.
`X-apiKey`	The Authorization header that contains the Api Key.

Response fields

Path	Type	Description
`airports[].icaoCode`	`String`	Airport ICAO code
`airports[].ident`	`String`	Airport SITA identifier
`airports[].city`	`String`	City code where Airport is located
`airports[]`	`Array`	Airport records returned
`airports[].name`	`String`	Airport name
`airports[].latitude`	`Number`	Airports Latitude position
`airports[].elevation`	`Number`	Airport altitude
`airports[].longitude`	`Number`	Airports Longitude position
`airports[].type`	`String`	Airport Type
`airports[].country`	`String`	Country Name where Airport is located
`airports[].countryCode`	`String`	Country Code where Airport is located
`airports[].timezone`	`String`	Airports Timezone
`airports[].continent`	`String`	Continent where Airport is located
`success`	`Boolean`	Indicates if request was correctly processed
`airports[].localCode`	`String`	Local airport code
`airports[].iataCode`	`String`	Airport IATA code
`airports[].region`	`String`	Region code where Airport is located

Curl request

$ curl 'https://data-qa.api.aero/v3/airports' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-apiKey: apikey_xyz'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 884

{
  "success" : true,
  "airports" : [ {
    "ident" : "UKFG",
    "type" : "AIRPORT",
    "elevation" : 721,
    "continent" : "EU",
    "countryCode" : "UA",
    "region" : "UA-43",
    "localCode" : "",
    "name" : "Gvardeyskoe Air Base",
    "iataCode" : "",
    "icaoCode" : "UKFG",
    "city" : "Sarabuz",
    "latitude" : 45.1150016784668,
    "longitude" : 33.97700119018555,
    "country" : "",
    "timezone" : ""
  }, {
    "ident" : "LSGG",
    "type" : "LARGE_AIRPORT",
    "elevation" : 1411,
    "continent" : "EU",
    "countryCode" : "CH",
    "region" : "CH-GE",
    "localCode" : "",
    "name" : "Geneva Cointrin International Airport",
    "iataCode" : "GVA",
    "icaoCode" : "LSGG",
    "city" : "Geneva",
    "latitude" : 45.1150016784668,
    "longitude" : 33.97700119018555,
    "country" : "",
    "timezone" : ""
  } ]
}

3.2.4 Get Distance between two Airports

Request headers

Name	Description
`Content-Type`	The Content-Type of this request.
`X-apiKey`	The Authorization header that contains the Api Key.

Response fields

Path	Type	Description
`success`	`Boolean`	Indicates if request was correctly processed
`units`	`String`	Unit used (KM/Mile)
`distance`	`String`	DistanceDto between both airports

Curl request

$ curl 'https://data-qa.api.aero/v3/airports/distance/LON/DXB' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-apiKey: apikey_xyz'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 74

{
  "success" : true,
  "distance" : "4,925,645.0",
  "units" : "km"
}

3.2.5 Get Nearest Airport

Request headers

Name	Description
`Content-Type`	The Content-Type of this request.
`X-apiKey`	The Authorization header that contains the Api Key.

Response fields

Path	Type	Description
`airports[].icaoCode`	`String`	Airport ICAO code
`airports[].ident`	`String`	Airport SITA identifier
`airports[].city`	`String`	City code where Airport is located
`airports[]`	`Array`	Airport records returned
`airports[].name`	`String`	Airport name
`airports[].latitude`	`Number`	Airports Latitude position
`airports[].elevation`	`Number`	Airport altitude
`airports[].longitude`	`Number`	Airports Longitude position
`airports[].type`	`String`	Airport Type
`airports[].country`	`String`	Country Name where Airport is located
`airports[].countryCode`	`String`	Country Code where Airport is located
`airports[].timezone`	`String`	Airports Timezone
`airports[].continent`	`String`	Continent where Airport is located
`success`	`Boolean`	Indicates if request was correctly processed
`airports[].localCode`	`String`	Local airport code
`airports[].iataCode`	`String`	Airport IATA code
`airports[].region`	`String`	Region code where Airport is located

Curl request

$ curl 'https://data-qa.api.aero/v3/airports/nearest/46.125485/31.254852' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-apiKey: apikey_xyz'

HTTP response

HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
Content-Length: 477

{
  "success" : true,
  "airports" : [ {
    "ident" : "LSGG",
    "type" : "LARGE_AIRPORT",
    "elevation" : 1411,
    "continent" : "EU",
    "countryCode" : "CH",
    "region" : "CH-GE",
    "localCode" : "",
    "name" : "Geneva Cointrin International Airport",
    "iataCode" : "GVA",
    "icaoCode" : "LSGG",
    "city" : "Geneva",
    "latitude" : 45.1150016784668,
    "longitude" : 33.97700119018555,
    "country" : "",
    "timezone" : ""
  } ]
}

3.2.6 Is Same Country Check

Request headers

Name	Description
`Content-Type`	The Content-Type of this request.
`X-apiKey`	The Authorization header that contains the Api Key.

Response fields

Path	Type	Description
`success`	`Boolean`	Indicates if request was correctly processed
`sameCountry`	`Boolean`	Boolean flag indicating if both airports are from the same country

Curl request

$ curl 'https://data-qa.api.aero/v3/airports/samecountry/LON/DXB' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-apiKey: apikey_xyz'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 50

{
  "success" : true,
  "sameCountry" : false
}

4 Error Response

4.1 Response fields

Path	Type	Description
`errors`	`Object`	`Object that holds the error information`
`errors.error[].description`	`String`	`Error Description`
`errors.error[]`	`Array`	`Array of errors`
`errors.error[].invalidParam`	`String`	`Indicates the invalid query parameter`
`errors.error[].code`	`Number`	`API Internal Error Code`

4.2 HTTP Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 159
{
  "errors" : {
  "error" : [ {
  "description" : "Error Description",
  "code" : 9999,
  "invalidParam" : "parameterName"
  } ]
  }
}

5 Appendix A - Airport Reference Use Cases

Scenario:	As an API user I want to make a request to the Airport Reference API to return all data for every airport
Request:	GET /data/v3/airports
Response:	Returns data for all airports available

Scenario:	As an API user I want to make a request to the Airport Reference API to return the distance between 2 airports
Request:	GET /data/v3/airports/distance/AMS/LYS
Response:	Returns the distance between AMS and LYS, default distance is in km, but can be set to miles

Scenario:	As an API user I want to make a request to the Airport Reference API to find the nearest airport to given latitude and longitude co-ordinates
Request:	GET /data/v3/airports/nearest/25.7685/-80.2974
Response:	Returns the nearest airport to the given latitude and longitude co-ordinates

Scenario:	As an API user I want to make a request to the Airport Reference API to return information about a given IATA/ICAO code
Request:	GET /data/v3/airports/MIA
Response:	Returns information for MIA airport

Scenario:	As an API user I want to make a request to the Airport Reference API to match airports by IATA/ICAO codes or airport name
Request:	GET /data/v3/airports/match/Miami
Response:	Returns information for Miami airport

Scenario:	As an API user I want to make a request to the Airport Reference API to determine if 2 given airports are in the same country
Request:	GET /data/v3/airports/samecountry/AMS/LYS
Response:	Determines if both airports are in the same country and returns the result

Last updated 2022-11-10 11:19:37 UTC

SITA Airport Reference API

About us

Contact