openapi: 3.1.0
info:
  title: Airport Gap REST Airports Distance API
  description: Airport Gap is a RESTful API designed to help developers practice API automation testing. It provides access to a database of worldwide airports including ICAO/IATA codes, location coordinates, elevation, and country information. The API also supports calculating distances between airports in miles, kilometers, and nautical miles, and allows authenticated users to save and manage favorite airports. Responses conform to the JSON:API specification. Data is sourced from OpenFlights.org under the Open Database License (ODbL 1.0).
  version: 1.0.0
  contact:
    url: https://airportgap.com
  license:
    name: MIT
    url: https://github.com/dennmart/airport_gap/blob/main/LICENCE
  x-source: https://airportgap.com/docs
servers:
- url: https://airportgap.com/api
  description: Production
tags:
- name: Distance
  description: Calculate great-circle distances between two airports.
paths:
  /airports/distance:
    post:
      operationId: calculateDistance
      summary: Calculate distance between airports
      description: Calculates the great-circle distance between two airports identified by their IATA codes. Returns the distance in miles, kilometers, and nautical miles.
      tags:
      - Distance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - from
              - to
              properties:
                from:
                  type: string
                  description: IATA code of the departure airport.
                  example: JFK
                to:
                  type: string
                  description: IATA code of the destination airport.
                  example: LAX
            example:
              from: JFK
              to: LAX
      responses:
        '200':
          description: Distance result between two airports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistanceData'
              example:
                data:
                  id: JFK-LAX
                  type: airport_distance
                  attributes:
                    from_airport:
                      id: JFK
                      type: airport
                      attributes:
                        name: John F. Kennedy International Airport
                        city: New York
                        country: United States
                        iata: JFK
                        icao: KJFK
                        latitude: '40.639751'
                        longitude: '-73.778925'
                        altitude: 13
                        timezone: America/New_York
                    to_airport:
                      id: LAX
                      type: airport
                      attributes:
                        name: Los Angeles International Airport
                        city: Los Angeles
                        country: United States
                        iata: LAX
                        icao: KLAX
                        latitude: '33.942536'
                        longitude: '-118.408075'
                        altitude: 125
                        timezone: America/Los_Angeles
                    miles: 2475.6
                    kilometers: 3984.2
                    nautical_miles: 2150.8
        '422':
          description: Missing or invalid IATA codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DistanceData:
      type: object
      description: JSON:API envelope for distance result.
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              description: Identifier composed of the two IATA codes.
              example: JFK-LAX
            type:
              type: string
              enum:
              - airport_distance
            attributes:
              $ref: '#/components/schemas/DistanceAttributes'
    Airport:
      type: object
      description: Represents a single airport record conforming to JSON:API.
      properties:
        id:
          type: string
          description: IATA airport code (e.g. "JFK").
          example: JFK
        type:
          type: string
          enum:
          - airport
          example: airport
        attributes:
          type: object
          properties:
            name:
              type: string
              description: Full name of the airport.
              example: John F. Kennedy International Airport
            city:
              type: string
              description: City where the airport is located.
              example: New York
            country:
              type: string
              description: Country where the airport is located.
              example: United States
            iata:
              type: string
              description: IATA airport code.
              example: JFK
            icao:
              type: string
              description: ICAO airport code.
              example: KJFK
            latitude:
              type: string
              description: Latitude coordinate of the airport.
              example: '40.639751'
            longitude:
              type: string
              description: Longitude coordinate of the airport.
              example: '-73.778925'
            altitude:
              type: integer
              description: Elevation of the airport in feet.
              example: 13
            timezone:
              type: string
              description: Timezone identifier.
              example: America/New_York
    DistanceAttributes:
      type: object
      description: Distance measurements between two airports.
      properties:
        from_airport:
          $ref: '#/components/schemas/Airport'
        to_airport:
          $ref: '#/components/schemas/Airport'
        miles:
          type: number
          format: float
          description: Distance in miles.
          example: 2475.6
        kilometers:
          type: number
          format: float
          description: Distance in kilometers.
          example: 3984.2
        nautical_miles:
          type: number
          format: float
          description: Distance in nautical miles.
          example: 2150.8
    ErrorResponse:
      type: object
      description: JSON:API error envelope.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
                description: HTTP status code string.
              title:
                type: string
                description: Short error title.
              detail:
                type: string
                description: Detailed error message.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: 'Token-based authentication. Include the token generated from POST /tokens. Header format: Authorization: Bearer token=<Your Airport Gap Token>'
externalDocs:
  description: Airport Gap API Documentation
  url: https://airportgap.com/docs