The Airport Gap API is a RESTful API used to access a database of airports, calculate distances between airports, and save your favorite airports to your account.

Authentication

The Airport Gap API uses API tokens to authenticate protected endpoints. You can generate a token for free.

Authentication to the API is done via Bearer Authentication. When making a request to a protected endpoint, you must send the token in the Authorization header.


        Authorization: Bearer token=<Your Airport Gap Token>

Please keep your API token secure. Do not share your token in publicly accessible areas such as client-side code, open source code repositories, etc.

Base URL

The base URL for all endpoints for the Airport Gap API is https://airportgap.com/api.

For example, to fetch all airports via the API, the full URL is a GET request to https://airportgap.com/api/airports.

Responses

All responses returned by the Airport Gap API follow the JSON:API specification. Please read the API endpoints reference for examples of successful responses.

Errors

Airport Gap uses common HTTP status codes to indicate if a request was successful or there was an error. Status codes in the 2xx range indicate a successful response. Status codes in the 4xx range indicate errors caused by your request, such as required parameters not sent. Status codes in the 5xx mean something went wrong with the Airport Gap application. Please read the API endpoints reference for examples of successful responses.

HTTP Status Codes

These are the common HTTP status codes used by the Airport Gap API:

200 (OK): Your request was successful.
201 (Created): Your request was successful and a new resource was created for your account.
204 (No Content): Your request was successful and no content is returned in the response body.
401 (Unauthorized): Your request was unsuccessful because you are not authenticated. Usually this means you didn't supply your API token or supplied an invalid token.
404 (Not Found): Your request was unsuccessful because you attempted to access a resource that doesn't exist.
422 (Unprocessable Entity): Your request was unsuccessful because you did not submit the necessary parameters for the endpoint.
429 (Too Many Request): Your request was unsuccessful because you accessed the Airport Gap API too many times in a short period. See the Rate Limiting section for more information.

Rate Limiting

You can make up to 100 requests per minute to any endpoint. Any request exceeding the rate limit will receive a 429 Too Many Requests response.

Requests are associated to your IP address and will reset every minute.

Pagination

Some endpoints that return multiple items will return up to a maximum of 30 items by default. You can fetch additional resources by sending the ?page parameter with the number of the page for the next set of resources.

Endpoints containing pagination will include an additional object with links to traverse the data, as specified in the Pagination section of the JSON:API specification. Please read the API endpoints reference for examples of paginated responses.

API endpoints reference

GET /airports

Returns all airports in the Airport Gap database. Results are paginated (30 airports per page).

Example request (cURL)


        curl https://airportgap.com/api/airports

Example of successful response Status: 200 OK

{
  "data": [{
      "attributes": {
        "altitude": 5282,
        "city": "Goroka",
        "country": "Papua New Guinea",
        "iata": "GKA",
        "icao": "AYGA",
        "latitude": "-6.08169",
        "longitude": "145.391998",
        "name": "Goroka Airport",
        "timezone": "Pacific/Port_Moresby"

      },
      "id": "GKA",
      "type": "airport"
    },
    {
      "attributes": {
        "altitude": 20,
        "city": "Madang",
        "country": "Papua New Guinea",
        "iata": "MAG",
        "icao": "AYMD",
        "latitude": "-5.20708",
        "longitude": "145.789001",
        "name": "Madang Airport",
        "timezone": "Pacific/Port_Moresby"
      },
      "id": "MAG",
      "type": "airport"
    },

    ...

    {
      "attributes": {
        "altitude": 1343,
        "city": "Brandon",
        "country": "Canada",
        "iata": "YBR",
        "icao": "CYBR",
        "latitude": "49.91",
        "longitude": "-99.951897",
        "name": "Brandon Municipal Airport",
        "timezone": "America/Winnipeg"
      },
      "id": "YBR",
      "type": "airport"
    },
    {
      "attributes": {
        "altitude": 90,
        "city": "Cambridge Bay",
        "country": "Canada",
        "iata": "YCB",
        "icao": "CYCB",
        "latitude": "69.108101",
        "longitude": "-105.138",
        "name": "Cambridge Bay Airport",
        "timezone": "America/Edmonton"
      },
      "id": "YCB",
      "type": "airport"
    }
  ],
  "links": {
    "first": "https://airportgap.com/api/airports",
    "last": "https://airportgap.com/api/airports?page=203",
    "next": "https://airportgap.com/api/airports?page=2",
    "prev": "https://airportgap.com/api/airports",
    "self": "https://airportgap.com/api/airports"
  }
}

GET /airports/:id

Returns the airport specified by the ID.

Required parameters

Parameter	Type	Description
id	String	The airport code (IATA location identifier) of the airport.

Example request (cURL)


        curl https://airportgap.com/api/airports/KIX

Example of successful response Status: 200 OK

{
  "data": {
    "attributes": {
      "altitude": 26,
      "city": "Osaka",
      "country": "Japan",
      "iata": "KIX",
      "icao": "RJBB",
      "latitude": "34.427299",
      "longitude": "135.244003",
      "name": "Kansai International Airport",
      "timezone": "Asia/Tokyo"
    },
    "id": "KIX",
    "type": "airport"
  }
}

POST /airports/distance

Calculates the distance between two airports and returns the distance in miles, kilometers, and nautical miles.

Required parameters

Parameter	Type	Description
from	String	The airport code (IATA location identifier) of the departure airport.
to	String	The airport code (IATA location identifier) of the destination airport.

Example request (cURL)


        curl -X POST -d "from=KIX&to=NRT" https://airportgap.com/api/airports/distance

Example of successful response Status: 200 OK

{
  "data": {
    "attributes": {
      "from_airport": {
        "altitude": 26,
        "city": "Osaka",
        "country": "Japan",
        "iata": "KIX",
        "icao": "RJBB",
        "id": 9230,
        "latitude": "34.427299",
        "longitude": "135.244003",
        "name": "Kansai International Airport",
        "timezone": "Asia/Tokyo"
      },
      "kilometers": 0.0,
      "miles": 0.0,
      "nautical_miles": 0.0,
      "to_airport": {
        "altitude": 26,
        "city": "Osaka",
        "country": "Japan",
        "iata": "KIX",
        "icao": "RJBB",
        "id": 9230,
        "latitude": "34.427299",
        "longitude": "135.244003",
        "name": "Kansai International Airport",
        "timezone": "Asia/Tokyo"
      }
    },
    "id": "KIX-KIX",
    "type": "airport_distance"
  }
}

POST /tokens

Returns the API token for your Airport Gap account.

Required parameters

Parameter	Type	Description
email	String	The email address for your Airport Gap account.
password	String	Your Airport Gap account password.

Example request (cURL)


        curl -X POST -d "[email protected]&password=airportgappassword" https://airportgap.com/api/tokens

Example of successful response Status: 200 OK

{
  "token": "<Your Airport Gap Token>"
}

GET /favorites

Authentication Required

Returns all the favorite airports saved to your Airport Gap account. Results are paginated (30 airports per page).

Example request (cURL)


        curl -H "Authorization: Token <Your Airport Gap Token>" https://airportgap.com/api/favorites

Example of successful response Status: 200 OK

{
  "data": [{
      "attributes": {
        "airport": {
          "altitude": 26,
          "city": "Osaka",
          "country": "Japan",
          "iata": "KIX",
          "icao": "RJBB",
          "id": 9230,
          "latitude": "34.427299",
          "longitude": "135.244003",
          "name": "Kansai International Airport",
          "timezone": "Asia/Tokyo"
        },
        "note": "My local airport"
      },
      "id": "22",
      "type": "favorite"
    },
    {
      "attributes": {
        "airport": {
          "altitude": 50,
          "city": "Osaka",
          "country": "Japan",
          "iata": "ITM",
          "icao": "RJOO",
          "id": 7836,
          "latitude": "34.7855",
          "longitude": "135.438004",
          "name": "Osaka International Airport",
          "timezone": "Asia/Tokyo"
        },
        "note": "Small airport nearby, great for travel within Japan"
      },
      "id": "23",
      "type": "favorite"
    },
    {
      "attributes": {
        "airport": {
          "altitude": 9,
          "city": "San Juan",
          "country": "Puerto Rico",
          "iata": "SJU",
          "icao": "TJSJ",
          "id": 8270,
          "latitude": "18.4394",
          "longitude": "-66.001801",
          "name": "Luis Munoz Marin International Airport",
          "timezone": "America/Puerto_Rico"
        },
        "note": "My home country airport, used when I go visit my family"
      },
      "id": "24",
      "type": "favorite"
    }
  ],
  "links": {
    "first": "https://airportgap.com/api/favorites",
    "last": "https://airportgap.com/api/favorites?page=1",
    "next": "https://airportgap.com/api/favorites",
    "prev": "https://airportgap.com/api/favorites",
    "self": "https://airportgap.com/api/favorites"
  }
}

GET /favorites/:id

Authentication Required

Returns the favorite airport from your Airport Gap account specified by the ID.

Required parameters

Parameter	Type	Description
id	Integer	The ID of the favorite record in your Airport Gap account.

Example request (cURL)


        curl -H "Authorization: Bearer token=<Your Airport Gap Token>" https://airportgap.com/api/favorites/22

Example of successful response Status: 200 OK

{
  "data": {
    "attributes": {
      "airport": {
        "altitude": 26,
        "city": "Osaka",
        "country": "Japan",
        "iata": "KIX",
        "icao": "RJBB",
        "id": 9230,
        "latitude": "34.427299",
        "longitude": "135.244003",
        "name": "Kansai International Airport",
        "timezone": "Asia/Tokyo"
      },
      "note": "My local airport"
    },
    "id": "22",
    "type": "favorite"
  }
}

POST /favorites

Authentication Required

Allows you to save a favorite airport to your Airport Gap account.

Required parameters

Parameter	Type	Description
airport_id	String	The airport code (IATA location identifier) of the airport.

Optional parameters

Parameter	Type	Description
note	String	A note you want to save about the airport.

Example request (cURL)


        curl -X POST -d "airport_id=JFK¬e=My usual layover when visiting family" -H "Authorization: Bearer token=<Your Airport Gap Token>" https://airportgap.com/api/favorites

Example of successful response Status: 201 Created

{
  "data": {
    "attributes": {
      "airport": {
        "altitude": 13,
        "city": "New York",
        "country": "United States",
        "iata": "JFK",
        "icao": "KJFK",
        "id": 9055,
        "latitude": "40.639801",
        "longitude": "-73.7789",
        "name": "John F Kennedy International Airport",
        "timezone": "America/New_York"
      },
      "note": "My usual layover when visiting family"
    },
    "id": "25",
    "type": "favorite"
  }
}

PATCH /airports/:id

Authentication Required

Allows you to update the note of one of your favorite airports in your Airport Gap account.

Required parameters

Parameter	Type	Description
id	String	The ID of the favorite record in your Airport Gap account.

Optional parameters

Parameter	Type	Description
note	String	A note you want to save about the airport.

Example request (cURL)


        curl -X PATCH -d "note=My usual layover when visiting family, although it's really far away..." -H "Authorization: Bearer token=<Your Airport Gap Token>" https://airportgap.com/api/favorites/25

Example of successful response Status: 200 OK

{
  "data": {
    "attributes": {
      "airport": {
        "altitude": 13,
        "city": "New York",
        "country": "United States",
        "iata": "JFK",
        "icao": "KJFK",
        "id": 9055,
        "latitude": "40.639801",
        "longitude": "-73.7789",
        "name": "John F Kennedy International Airport",
        "timezone": "America/New_York"
      },
      "note": "My usual layover when visiting family, although it's really far away..."
    },
    "id": "25",
    "type": "favorite"
  }
}

DELETE /favorites/:id

Authentication Required

Deletes one of your favorite airports from your Airport Gap account.

Required parameters

Parameter	Type	Description
id	String	The ID of the favorite record in your Airport Gap account.

Example request (cURL)


        curl -X DELETE -H "Authorization: Bearer token=<Your Airport Gap Token>" https://airportgap.com/api/favorites/25

Example of successful response Status: 204 No Content

No content is returned in the response body upon successful deletion.

DELETE /favorites/clear_all

Authentication Required

Clears all of your favorite airports from your Airport Gap account. (USE WITH CAUTION!)

Example request (cURL)


        curl -X DELETE -H "Authorization: Bearer token=<Your Airport Gap Token>" https://airportgap.com/api/favorites/clear_all

Example of successful response Status: 204 No Content

No content is returned in the response body upon successful deletion of all favorites.