openapi: 3.1.0
info:
  title: AirLabs Cities Database API
  version: '9'
  summary: Reference dataset of global cities keyed by IATA metropolitan codes.
  description: >-
    The AirLabs Cities Database API returns a list of global cities filterable
    by IATA city_code, ISO 2 country_code, or selected fields. City data
    complements and extends the AirLabs airports dataset for travel search,
    mapping, and geocoding experiences.
  contact:
    name: AirLabs Support
    url: https://airlabs.co/contact
  license:
    name: AirLabs Terms of Service
    url: https://airlabs.co/terms
servers:
  - url: https://airlabs.co/api/v9
    description: AirLabs production API
security:
  - apiKey: []
paths:
  /cities:
    get:
      operationId: listCities
      summary: List cities
      description: >-
        Returns a list of cities, optionally filtered by IATA metropolitan
        city_code, ISO 2 country_code, or restricted to a specified set of
        fields.
      tags:
        - Cities
      parameters:
        - in: query
          name: api_key
          description: AirLabs API key from the account dashboard.
          required: true
          schema:
            type: string
        - in: query
          name: city_code
          description: IATA metropolitan city code (e.g. NYC, LON, PAR).
          schema:
            type: string
        - in: query
          name: country_code
          description: ISO 2 country code (e.g. US, GB, FR).
          schema:
            type: string
        - in: query
          name: _fields
          description: Comma-separated list of fields to include in the response.
          schema:
            type: string
      responses:
        '200':
          description: An array of city objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  request:
                    type: object
                    properties:
                      lang:
                        type: string
                      currency:
                        type: string
                      time:
                        type: integer
                      id:
                        type: string
                      server:
                        type: string
                  response:
                    type: array
                    items:
                      $ref: '#/components/schemas/City'
        '401':
          description: Invalid or missing API key.
        '429':
          description: Rate limit exceeded.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: api_key
  schemas:
    City:
      type: object
      properties:
        name:
          type: string
          description: English name of the city.
        city_code:
          type: string
          description: IATA metropolitan area code.
        un_code:
          type: string
          description: UN/LOCODE for the city.
        slug:
          type: string
          description: SEO-friendly slug.
        country_code:
          type: string
          description: ISO 2 country code.
        lat:
          type: number
          format: float
          description: Latitude in decimal degrees.
        lng:
          type: number
          format: float
          description: Longitude in decimal degrees.
        elevation:
          type: integer
          description: Elevation in meters.
        timezone:
          type: string
          description: IANA timezone identifier.
        population:
          type: integer
          description: Population count.
        wikipedia:
          type: string
          format: uri
          description: Wikipedia article URL for the city.
        names:
          type: object
          additionalProperties:
            type: string
          description: Multilingual city names keyed by ISO 639-1 language code.