openapi: 3.0.3
info:
  title: FlightLabs Aircraft Geography API
  description: 'Real-time and historical flight tracker and status API providing live data for flights, airports, schedules, timetables, IATA codes, airline routes, and flight pricing globally. Operated by Zyla Labs, FlightLabs offers 16+ endpoints covering live flights, flight delays, future predictions, airline routes, and flight pricing.

    '
  version: '1.0'
  contact:
    name: FlightLabs Support
    email: hello@goflightlabs.com
    url: https://www.goflightlabs.com
  termsOfService: https://www.goflightlabs.com/terms
  license:
    name: Commercial
    url: https://www.goflightlabs.com/pricing
servers:
- url: https://app.goflightlabs.com
  description: FlightLabs Production API
security:
- AccessKey: []
tags:
- name: Geography
  description: Countries and cities reference data endpoints
paths:
  /countries:
    get:
      operationId: getCountries
      summary: Retrieve Countries
      description: 'Retrieve country reference data including codes, names, population, continent, and currency information.

        '
      tags:
      - Geography
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: codeIso2Country
        in: query
        description: Country ISO 2-letter code
        required: false
        schema:
          type: string
          example: US
      - name: nameCountry
        in: query
        description: Country name filter
        required: false
        schema:
          type: string
          example: United States
      responses:
        '200':
          description: Successful response with country data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountriesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /cities:
    get:
      operationId: getCities
      summary: Cities By IATA Code
      description: 'Retrieve city reference data including IATA codes, coordinates, timezone, population, and multilingual names.

        '
      tags:
      - Geography
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: codeIataCity
        in: query
        description: City IATA code
        required: false
        schema:
          type: string
          example: NYC
      - name: codeIso2Country
        in: query
        description: Country ISO 2-letter code
        required: false
        schema:
          type: string
          example: US
      responses:
        '200':
          description: Successful response with city data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitiesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /autocomplete-cities:
    get:
      operationId: autocompleteCities
      summary: Autocomplete Cities
      description: 'Search for cities by partial name or abbreviation for autocomplete functionality. Returns matching cities with IATA codes, country, and geographic data.

        '
      tags:
      - Geography
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - name: city
        in: query
        description: City name or abbreviation to search for
        required: true
        schema:
          type: string
          example: New York
      responses:
        '200':
          description: Successful response with matching cities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitiesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CountryData:
      type: object
      description: Country reference data
      properties:
        countryId:
          type: string
          example: '226'
        nameCountry:
          type: string
          example: United States
        codeIso2Country:
          type: string
          example: US
        codeIso3Country:
          type: string
          example: USA
        numericIso:
          type: string
          example: '840'
        codeIataCountry:
          type: string
          example: US
        nameContinent:
          type: string
          example: North America
        codeContinentIata:
          type: string
          example: NA
        population:
          type: integer
          example: 331000000
        currencyCode:
          type: string
          example: USD
        currencyName:
          type: string
          example: US Dollar
        languages:
          type: string
          example: en-US
        nameTranslations:
          type: string
          example: United States of America
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              example: 101
            type:
              type: string
              example: invalid_access_key
            info:
              type: string
              example: You have not supplied a valid API Access Key.
    CountriesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/CountryData'
    CitiesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/CityData'
    CityData:
      type: object
      description: City reference data
      properties:
        cityId:
          type: string
          example: '3400'
        nameCity:
          type: string
          example: New York
        codeIataCity:
          type: string
          example: NYC
        codeIso2Country:
          type: string
          example: US
        latitudeCity:
          type: number
          format: float
          example: 40.7128
        longitudeCity:
          type: number
          format: float
          example: -74.006
        timezone:
          type: string
          example: America/New_York
        GMT:
          type: string
          example: '-5'
        population:
          type: integer
          example: 8336817
        nameTranslations:
          type: string
          example: New York,Nueva York
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of results to return (integer, up to 10000)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        example: 100
    AccessKey:
      name: access_key
      in: query
      description: Your FlightLabs API access key
      required: true
      schema:
        type: string
        example: YOUR_ACCESS_KEY
  securitySchemes:
    AccessKey:
      type: apiKey
      in: query
      name: access_key
      description: API key obtained from your FlightLabs dashboard
externalDocs:
  description: FlightLabs API Documentation
  url: https://www.goflightlabs.com/dashboard#api-documentation