api-ninjas-com Airports API

openapi: 3.2.0
info:
  title: Ninjas Airports API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Airports
  description: The Airports API provides vital information on over 85,000 airports, heliports, seaplane bases, and small airfields worldwide. Includes endpoints for IATA/ICAO code conversion, great-circle distance between airports, autocomplete suggestions, and nearest-airport lookup by coordinate.
paths:
  /v1/airports:
    get:
      summary: Get airport information
      description: Returns airports matching filters such as IATA/ICAO code, name, city, country, region, elevation, size, or runway length. For typeahead suggestions use /airportsuggest.
      operationId: getAirports
      security:
      - ApiKeyAuth: []
      parameters:
      - name: iata
        in: query
        description: International Air Transport Association (IATA) airport code (typically 3 characters). Supports partial, case-insensitive matching (substring search).
        required: false
        schema:
          type: string
      - name: icao
        in: query
        description: International Civil Aviation Organization (ICAO) airport code (typically 4 characters). Supports partial, case-insensitive matching (substring search).
        required: false
        schema:
          type: string
      - name: name
        in: query
        description: Airport name. Supports partial matching (substring search). Premium only.
        required: false
        schema:
          type: string
      - name: country
        in: query
        description: Airport country. Must be 2-character ISO-2 country code.
        required: false
        schema:
          type: string
      - name: region
        in: query
        description: Administrative region such as state or province within a country. Supports partial, case-insensitive matching (substring search). Premium only.
        required: false
        schema:
          type: string
      - name: city
        in: query
        description: Airport city. Supports partial, case-insensitive matching (substring search). Premium only.
        required: false
        schema:
          type: string
      - name: q
        in: query
        description: Free-text search across airport name, city, codes, and alternate-name keywords. Premium only.
        required: false
        schema:
          type: string
      - name: timezone
        in: query
        description: Airport timezone.
        required: false
        schema:
          type: string
      - name: min_elevation
        in: query
        description: Minimum airport elevation in feet.
        required: false
        schema:
          type: integer
      - name: max_elevation
        in: query
        description: Maximum airport elevation in feet.
        required: false
        schema:
          type: integer
      - name: size
        in: query
        description: Airport size.
        required: false
        schema:
          type: string
          enum:
          - large
          - medium
          - small
      - name: has_iata
        in: query
        description: Filter by whether the airport has an IATA code.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: min_runway_length
        in: query
        description: Minimum length (in feet) of at least one runway at the airport.
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of results to return. Must be between 1 and 100. Default is 10.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - name: sort
        in: query
        description: Sort order for results. Default is passengers.
        required: false
        schema:
          type: string
          enum:
          - passengers
          - name
          - elevation
          - runway_length
          default: passengers
      - name: order
        in: query
        description: Sort direction. Default is desc.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: offset
        in: query
        description: Number of results to offset for pagination.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: A list of airports.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Airport'
        '400':
          description: Bad request. Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Airports
  /v1/airportslist:
    get:
      summary: Get a list of airport codes and names. Premium only
      description: Returns a paginated list of airport codes and names. For filtered airport detail use /airports. Requires a premium subscription.
      operationId: getAirportsList
      security:
      - ApiKeyAuth: []
      parameters:
      - name: offset
        in: query
        description: Number of results to offset for pagination. Default is 0. Premium only.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: A list of airport codes and names.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    ident:
                      type: string
                      description: Universal airport identifier. Equals the ICAO code where one exists, otherwise a local or regional code.
                    icao:
                      type: string
                      description: International Civil Aviation Organization (ICAO) 4-character airport code.
                    iata:
                      type: string
                      description: International Air Transport Association (IATA) 3-character airport code.
                    name:
                      type: string
                      description: Airport name.
                    type:
                      type: string
                      enum:
                      - large_airport
                      - medium_airport
                      - small_airport
                      - heliport
                      - seaplane_base
                      - balloonport
                      - closed
                      description: 'Facility type: large_airport, medium_airport, small_airport, heliport, seaplane_base, balloonport, or closed.'
        '400':
          description: Bad request. Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Airports
  /v1/airportconvert:
    get:
      summary: Convert between IATA and ICAO airport codes. Premium only
      description: Converts an airport code between IATA and ICAO. Pass exactly one of `iata`, `icao`, or `code` (auto-detected). Requires a premium subscription.
      operationId: convertAirportCode
      security:
      - ApiKeyAuth: []
      parameters:
      - name: iata
        in: query
        description: 3-character IATA airport code. Exactly one of iata, icao, or code must be provided.
        required: false
        schema:
          type: string
      - name: icao
        in: query
        description: 4-character ICAO airport code. Exactly one of iata, icao, or code must be provided.
        required: false
        schema:
          type: string
      - name: code
        in: query
        description: Auto-detected IATA (3 chars) or ICAO (4 chars) code. Exactly one of iata, icao, or code must be provided.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The matched airport's details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportConvert'
        '400':
          description: Bad request. Invalid request parameters or airport not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Airports
  /v1/airportdistance:
    get:
      summary: Calculate the great-circle distance, initial bearing, and estimated flight time…
      description: Calculates great-circle distance, initial bearing, and estimated flight time between two airports. Requires `from` and `to`. Requires a premium subscription.
      operationId: airportDistance
      security:
      - ApiKeyAuth: []
      parameters:
      - name: from
        in: query
        description: Origin airport - IATA (3 chars) or ICAO (4 chars) code.
        required: true
        schema:
          type: string
      - name: to
        in: query
        description: Destination airport - IATA (3 chars) or ICAO (4 chars) code.
        required: true
        schema:
          type: string
      - name: units
        in: query
        description: Distance units. Default is km.
        required: false
        schema:
          type: string
          enum:
          - km
          - mi
          - nm
          default: km
      responses:
        '200':
          description: Distance, bearing, and estimated flight time between the two airports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDistance'
        '400':
          description: Bad request. Invalid request parameters or airport not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Airports
  /v1/airportsuggest:
    get:
      summary: Autocomplete / typeahead suggestions for airport search.
      description: Returns autocomplete suggestions for airport search, matching IATA, ICAO, name, and city. Requires a `q` of at least 2 characters. Requires a premium subscription.
      operationId: airportSuggest
      security:
      - ApiKeyAuth: []
      parameters:
      - name: q
        in: query
        description: Query string. Must be at least 2 characters.
        required: true
        schema:
          type: string
          minLength: 2
      - name: country
        in: query
        description: Restrict results to a country. Must be a 2-character ISO country code.
        required: false
        schema:
          type: string
      - name: size
        in: query
        description: Restrict results to a size.
        required: false
        schema:
          type: string
          enum:
          - large
          - medium
          - small
      - name: limit
        in: query
        description: Maximum number of results to return. Must be between 1 and 3. Default is 3.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 3
          default: 3
      responses:
        '200':
          description: A list of compact airport records ranked by match quality and size.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AirportSuggestItem'
        '400':
          description: Bad request. Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Airports
  /v1/closestairport:
    get:
      summary: Find the airports nearest to a given latitude/longitude.
      description: Returns the airports nearest a coordinate, sorted by airport size then by distance. Requires `lat` and `lon`. Requires a premium subscription.
      operationId: closestAirport
      security:
      - ApiKeyAuth: []
      parameters:
      - name: lat
        in: query
        description: Latitude of the search center, in decimal degrees.
        required: true
        schema:
          type: number
          format: double
          minimum: -90
          maximum: 90
      - name: lon
        in: query
        description: Longitude of the search center, in decimal degrees.
        required: true
        schema:
          type: number
          format: double
          minimum: -180
          maximum: 180
      - name: radius
        in: query
        description: Search radius in kilometres. Default is 50, maximum is 500.
        required: false
        schema:
          type: number
          format: double
          minimum: 1
          maximum: 500
          default: 50
      - name: size
        in: query
        description: Restrict to airport size.
        required: false
        schema:
          type: string
          enum:
          - large
          - medium
          - small
      - name: has_iata
        in: query
        description: Filter by whether the airport has an IATA code.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: min_runway_length
        in: query
        description: Minimum runway length in feet.
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of results to return. Must be between 1 and 50. Default is 10.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      - name: units
        in: query
        description: Distance units. Default is km.
        required: false
        schema:
          type: string
          enum:
          - km
          - mi
          default: km
      responses:
        '200':
          description: A list of nearby airports sorted by size (largest first) then by distance ascending.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClosestAirport'
        '400':
          description: Bad request. Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Airports
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message.
    Airport:
      type: object
      properties:
        icao:
          type: string
          description: International Civil Aviation Organization (ICAO) 4-character airport code.
        ident:
          type: string
          description: Universal airport identifier. Equals the ICAO code where one exists, otherwise a local or regional code.
        iata:
          type: string
          description: International Air Transport Association (IATA) 3-character airport code.
        name:
          type: string
          description: Airport name.
        city:
          type: string
          description: Airport city.
        region:
          type: string
          description: Administrative region such as state or province within a country.
        region_code:
          type: string
          description: ISO 3166-2 region code (e.g. US-CA).
        country:
          type: string
          description: Airport country. Must be 2-character ISO-2 country code.
        country_name:
          type: string
          description: Full country name.
        continent:
          type: string
          enum:
          - AF
          - AN
          - AS
          - EU
          - NA
          - OC
          - SA
          description: Continent code (AF, AN, AS, EU, NA, OC, SA).
        elevation_ft:
          type: integer
          description: Airport elevation in feet.
        elevation_m:
          type: number
          format: double
          description: Airport elevation in meters.
        latitude:
          type: number
          format: double
          description: Latitude of the airport.
        longitude:
          type: number
          format: double
          description: Longitude of the airport.
        timezone:
          type: string
          description: Airport timezone.
        type:
          type: string
          enum:
          - large_airport
          - medium_airport
          - small_airport
          - heliport
          - seaplane_base
          - balloonport
          - closed
          description: 'Facility type: large_airport, medium_airport, small_airport, heliport, seaplane_base, balloonport, or closed.'
        size:
          type: string
          description: Airport size.
          enum:
          - large
          - medium
          - small
        scheduled_service:
          type: boolean
          description: Whether the airport has scheduled airline service.
        is_closed:
          type: boolean
          description: Whether the facility is permanently closed.
        gps_code:
          type: string
          description: GPS/navigation database code.
        local_code:
          type:
          - string
          - 'null'
          description: Local/national airport code.
        home_link:
          type: string
          description: Official airport website URL.
        wikipedia_link:
          type: string
          description: Wikipedia article URL.
        keywords:
          type: array
          items:
            type: string
          description: Array of alternate names and codes used for search.
        num_runways:
          type: integer
          description: Number of runways at the airport.
        longest_runway_ft:
          type: integer
          description: Length of the longest runway in feet.
        runways:
          type: array
          description: Array of runway objects.
          items:
            $ref: '#/components/schemas/Runway'
        estimated_annual_passengers:
          type: integer
          description: Estimated yearly passenger volume.
    Runway:
      type: object
      properties:
        length:
          type: integer
          description: Runway length in feet.
        width:
          type: integer
          description: Runway width in feet.
        has_lights:
          type: boolean
          description: Whether the runway has lights.
        surface:
          type: string
          description: Raw surface description (e.g. ASP).
        surface_category:
          type: string
          enum:
          - paved
          - unpaved
          - water
          - unknown
          description: 'Normalized surface: paved, unpaved, water, or unknown.'
        closed:
          type: boolean
          description: Whether the runway is closed.
        le_ident:
          type: string
          description: Runway low-end designator (e.g. 09L).
        he_ident:
          type: string
          description: Runway high-end designator (e.g. 27R).
        le_heading_deg:
          type: number
          format: double
          description: True heading of the low runway end in degrees.
        he_heading_deg:
          type: number
          format: double
          description: True heading of the high runway end in degrees.
    AirportSuggestItem:
      type: object
      properties:
        icao:
          type: string
          description: International Civil Aviation Organization (ICAO) 4-character airport code.
        iata:
          type: string
          description: International Air Transport Association (IATA) 3-character airport code.
        ident:
          type: string
          description: Universal airport identifier. Equals the ICAO code where one exists, otherwise a local or regional code.
        name:
          type: string
          description: Airport name.
        city:
          type: string
          description: Airport city.
        country:
          type: string
          description: 2-letter ISO country code.
        type:
          type: string
          enum:
          - large_airport
          - medium_airport
          - small_airport
          - heliport
          - seaplane_base
          - balloonport
          - closed
          description: 'Facility type: large_airport, medium_airport, small_airport, heliport, seaplane_base, balloonport, or closed.'
        size:
          type: string
          description: Airport size.
          enum:
          - large
          - medium
          - small
    AirportDistance:
      type: object
      properties:
        from:
          type: string
          description: Origin airport code as provided in the request (uppercased).
        to:
          type: string
          description: Destination airport code as provided in the request (uppercased).
        distance:
          type: number
          format: double
          description: Great-circle distance in the requested units.
        bearing_initial:
          type: number
          format: double
          description: Initial bearing from origin to destination, in degrees true (0-360).
        unit:
          type: string
          description: Units used for the distance field.
          enum:
          - km
          - mi
          - nm
        estimated_flight_time_minutes:
          type: integer
          description: Approximate total flight time in minutes, assuming an 800 km/h cruise plus 30 minutes of ground/climb/descent overhead.
    AirportConvert:
      type: object
      properties:
        icao:
          type: string
          description: International Civil Aviation Organization (ICAO) 4-character airport code.
        iata:
          type: string
          description: International Air Transport Association (IATA) 3-character airport code.
        ident:
          type: string
          description: Universal airport identifier. Equals the ICAO code where one exists, otherwise a local or regional code.
        name:
          type: string
          description: Airport name.
        city:
          type: string
          description: Airport city.
        region:
          type: string
          description: Administrative region such as state or province within a country.
        region_code:
          type: string
          description: ISO 3166-2 region code (e.g. US-CA).
        country:
          type: string
          description: 2-letter ISO country code.
        country_name:
          type: string
          description: Full country name.
        continent:
          type: string
          enum:
          - AF
          - AN
          - AS
          - EU
          - NA
          - OC
          - SA
          description: Continent code (AF, AN, AS, EU, NA, OC, SA).
        elevation_ft:
          type: integer
          description: Airport elevation in feet.
        elevation_m:
          type: number
          format: double
          description: Airport elevation in meters.
        latitude:
          type: number
          format: double
          description: Latitude of the airport.
        longitude:
          type: number
          format: double
          description: Longitude of the airport.
        timezone:
          type: string
          description: Airport timezone.
        type:
          type: string
          enum:
          - large_airport
          - medium_airport
          - small_airport
          - heliport
          - seaplane_base
          - balloonport
          - closed
          description: 'Facility type: large_airport, medium_airport, small_airport, heliport, seaplane_base, balloonport, or closed.'
        size:
          type: string
          description: Airport size.
          enum:
          - large
          - medium
          - small
        scheduled_service:
          type: boolean
          description: Whether the airport has scheduled airline service.
        is_closed:
          type: boolean
          description: Whether the facility is permanently closed.
        gps_code:
          type: string
          description: GPS/navigation database code.
        local_code:
          type:
          - string
          - 'null'
          description: Local/national airport code.
    ClosestAirport:
      type: object
      properties:
        icao:
          type: string
          description: International Civil Aviation Organization (ICAO) 4-character airport code.
        ident:
          type: string
          description: Universal airport identifier. Equals the ICAO code where one exists, otherwise a local or regional code.
        iata:
          type: string
          description: International Air Transport Association (IATA) 3-character airport code.
        name:
          type: string
          description: Airport name.
        city:
          type: string
          description: Airport city.
        region:
          type: string
          description: Administrative region such as state or province within a country.
        region_code:
          type: string
          description: ISO 3166-2 region code (e.g. US-CA).
        country:
          type: string
          description: 2-letter ISO country code.
        country_name:
          type: string
          description: Full country name.
        continent:
          type: string
          enum:
          - AF
          - AN
          - AS
          - EU
          - NA
          - OC
          - SA
          description: Continent code (AF, AN, AS, EU, NA, OC, SA).
        elevation_ft:
          type: integer
          description: Airport elevation in feet.
        elevation_m:
          type: number
          format: double
          description: Airport elevation in meters.
        latitude:
          type: number
          format: double
          description: Latitude of the airport.
        longitude:
          type: number
          format: double
          description: Longitude of the airport.
        timezone:
          type: string
          description: Airport timezone.
        type:
          type: string
          enum:
          - large_airport
          - medium_airport
          - small_airport
          - heliport
          - seaplane_base
          - balloonport
          - closed
          description: 'Facility type: large_airport, medium_airport, small_airport, heliport, seaplane_base, balloonport, or closed.'
        size:
          type: string
          description: Airport size.
          enum:
          - large
          - medium
          - small
        scheduled_service:
          type: boolean
          description: Whether the airport has scheduled airline service.
        is_closed:
          type: boolean
          description: Whether the facility is permanently closed.
        num_runways:
          type: integer
          description: Number of runways at the airport.
        longest_runway_ft:
          type: integer
          description: Length of the longest runway in feet.
        distance:
          type: number
          format: double
          description: Great-circle distance from the requested coordinate, in the requested units.
        bearing:
          type: number
          format: double
          description: Initial bearing from the requested coordinate to the airport, in degrees true (0-360).
        distance_unit:
          type: string
          description: Units used for the distance field.
          enum:
          - km
          - mi
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api