swagger: '2.0'
info:
  version: 1.2.3
  title: Airport & City Search
  x-status: validated
  x-tags:
    - '#ama-for-dev'
  x-release-note:
    '1.2':
      - Remove parameter onlyMajor
      - Correct example
    '1.1':
      - AFD-1091 - change from "traveller" to "traveler"
      - change default value of view indicator to FULL
      - Change search algorithm
      - Addition of "id" for location
      - New operation GET Airport or City by id
      - Traveler score become interger (PTR 14827552)
      - Change the option parameter into view and onlyMajor parameter
      - add a characters restriction on keyword parameter
    '1.0':
      - Initial Version
  description: |-

    Before using this API, we recommend you read our **[Authorization Guide](https://developers.amadeus.com/self-service/apis-docs/guides/authorization-262)** for more information on how to generate an access token. 

    Please also be aware that our test environment is based on a subset of the production, in test this API only contains data from the United States, Spain, United Kingdom, Germany and India. 
host: test.api.amadeus.com
basePath: /v1
schemes:
  - https
consumes:
  - application/vnd.amadeus+json
produces:
  - application/vnd.amadeus+json
paths:
  /reference-data/locations:
    get:
      tags:
        - location
      operationId: getAirportCitySearch
      summary: Returns a list of airports and cities matching a given keyword.
      parameters:
        - name: subType
          description: sub type of the location (AIRPORT and/or CITY)
          in: query
          required: true
          type: array
          items:
            type: string
            enum:
              - AIRPORT
              - CITY
          collectionFormat: csv
          x-example: CITY
        - name: keyword
          description: |-
            keyword that should represent the start of a word in a city or airport name or code. 
            Supported charaters are: A-Za-z0-9./:-'()"
          in: query
          required: true
          type: string
          x-example: MUC
          pattern: '[A-Za-z0-9./:()''"-]'
        - name: countryCode
          description: 'Country code of the location using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code format (e.g. US).'
          in: query
          required: false
          type: string
        - $ref: '#/parameters/pageLimit'
        - $ref: '#/parameters/pageOffset'
        - $ref: '#/parameters/sort'
        - $ref: '#/parameters/view'
      responses:
        '200':
          $ref: '#/responses/airport-city-autocomplete'
        '400':
          $ref: '#/responses/400'
        default:
          $ref: '#/responses/500'
      description: ''
  '/reference-data/locations/{locationId}':
    get:
      tags:
        - location
      operationId: getAirportCity
      summary: Returns a specific airports or cities based on its id.
      parameters:
        - $ref: '#/parameters/locationId'
      responses:
        '200':
          $ref: '#/responses/airport-city'
        '400':
          $ref: '#/responses/400_GET-Id'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/500'
      description: ''
parameters:
  pageLimit:
    name: 'page[limit]'
    description: maximum items in one page
    required: false
    in: query
    type: integer
    default: 10
  pageOffset:
    name: 'page[offset]'
    description: start index of the requested page
    required: false
    in: query
    type: integer
    default: 0
  sort:
    name: sort
    description: |
      defines on which attribute the sorting will be done:
      * analytics.travelers.score - sort by the number of travelers by airport or city, the airports and cities with the highest traffic are on top of the results
    required: false
    in: query
    type: string
    default: analytics.travelers.score
    enum:
      - analytics.travelers.score
  view:
    name: view
    description: |
      select the level of information of the reply:
      * LIGHT - Gives only the IATACode, name, detailedName, cityName and countryName
      * FULL - Adds on top of the LIGHT information the timeZoneOffset, geocode, detailed address and travelers.score
      default option is FULL
    required: false
    in: query
    default: FULL
    type: string
    enum:
      - LIGHT
      - FULL
  locationId:
    name: locationId
    description: identifier of the location
    required: true
    in: path
    type: string
    x-example: CMUC
definitions:
  Location:
    properties:
      id:
        description: id of the ressource
        type: string
      self:
        $ref: '#/definitions/Links'
      type:
        description: the resource name
        type: string
        example: location
      subType:
        description: location sub type
        type: string
        enum:
          - AIRPORT
          - CITY
          - POINT_OF_INTEREST
          - DISTRICT
        example: AIRPORT
      name:
        description: short name of the location
        type: string
        example: Paris CDG
      detailedName:
        description: detailed name of the location. For a city location it contains city name and country code. For an airport location it contains city name; country code and airport full name
        type: string
        example: 'Paris/FR: Charles de Gaulle'
      timeZoneOffset:
        description: timezone offset of the location at the date of the API call (including daylight saving time)
        type: string
        example: '+01:00'
      iataCode:
        description: 'IATA code of the location. ([IATA table codes](http://www.iata.org/publications/Pages/code-search.aspx) here)'
        type: string
        example: CDG
      geoCode:
        $ref: '#/definitions/GeoCode'
      address:
        $ref: '#/definitions/Address'
      distance:
        $ref: '#/definitions/Distance'
      analytics:
        $ref: '#/definitions/Analytics'
      relevance:
        type: number
        format: double
        description: score value calculated based on distance and analytics
        example: 9.6584
      category:
        description: category of the location
        type: string
        enum:
          - SIGHTS
          - BEACH_PARK
          - HISTORICAL
          - NIGHTLIFE
          - RESTAURANT
          - SHOPPING
        example: HISTORICAL
      tags:
        description: list of tags related to the location
        type: array
        items:
          type: string
          example:
            - grocery
            - japanese
            - cafe
      rank:
        description: the rank is the position compared to other locations based on how famous is a place. 1 being the highest.
        type: string
        example: 1
  Address:
    properties:
      cityName:
        description: name of the city of the location; equal to name if the location is a city
        type: string
        example: Paris
      cityCode:
        description: IATA code of the city of the location; equal to IATAcode if the location is a city
        type: string
        example: PAR
      countryName:
        description: name of the country of the location
        type: string
        example: France
      countryCode:
        description: code of the country of the location in ISO standard
        type: string
        example: FR
      stateCode:
        description: code of the state of the location if any
        type: string
        example: TO
      regionCode:
        description: code of the region of the location in ISO standard
        type: string
        example: EUROP
  Distance:
    properties:
      value:
        description: great-circle distance between two locations. This distance thus do not take into account traffic conditions; international boundaries; mountains; water; or other elements that might make the a nearby location hard to reach.
        type: integer
        example: 152
      unit:
        description: unit of the distance
        type: string
        example: KM
        enum:
          - KM
          - MI
  GeoCode:
    properties:
      latitude:
        description: latitude of the location
        type: number
        format: double
        example: 43.580418
      longitude:
        description: longitude of the location
        type: number
        format: double
        example: 7.125102
  Analytics:
    properties:
      travelers:
        $ref: '#/definitions/Travelers'
  Travelers:
    properties:
      score:
        type: number
        format: integer
        description: Approximate score for ranking purposes calculated based on number of travelers in the location.
        example: 68
  Error_400:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/Issue'
    required:
      - errors
    example:
      errors:
        - status: 400
          code: 477
          title: INVALID FORMAT
          detail: invalid query parameter format
          source:
            parameter: airport
            example: CDG
  Error_404:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/Issue'
    required:
      - errors
    example:
      errors:
        - status: 404
          code: 1797
          title: NOT FOUND
          detail: no response found for this query parameter
          source:
            parameter: airport
  Error_500:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/Issue'
    required:
      - errors
    example:
      errors:
        - status: 500
          code: 141
          title: SYSTEM ERROR HAS OCCURRED
  Issue:
    properties:
      status:
        description: the HTTP status code applicable to this error
        type: integer
      code:
        description: an application-specific error code
        type: integer
        format: int64
      title:
        description: a short summary of the error
        type: string
      detail:
        description: explanation of the error
        type: string
      source:
        type: object
        title: Issue_Source
        description: an object containing references to the source of the error
        maxProperties: 1
        properties:
          pointer:
            description: 'a JSON Pointer [RFC6901] to the associated entity in the request document'
            type: string
          parameter:
            description: a string indicating which URI query parameter caused the issue
            type: string
          example:
            description: a string indicating an example of the right value
            type: string
  Collection_Meta:
    title: Collection_Meta
    properties:
      count:
        type: integer
        example: 1
      links:
        title: CollectionLinks
        properties:
          self:
            type: string
            format: uri
            example: 'https://test.api.amadeus.com/v1/area/resources?...'
          next:
            type: string
            format: uri
            example: 'https://test.api.amadeus.com/v1/area/resources?...'
          previous:
            type: string
            format: uri
            example: 'https://test.api.amadeus.com/v1/area/resources?...'
          last:
            type: string
            format: uri
            example: 'https://test.api.amadeus.com/v1/area/resources?...'
          first:
            type: string
            format: uri
            example: 'https://test.api.amadeus.com/v1/area/resources?...'
          up:
            type: string
            format: uri
            example: 'https://test.api.amadeus.com/v1/area/resources?...'
        example:
          self: 'https://test.api.amadeus.com/v1/area/resources?param=value'
  Links:
    required:
      - href
    properties:
      href:
        type: string
        format: uri
      methods:
        type: array
        items:
          type: string
          enum:
            - GET
            - PUT
            - DELETE
            - POST
            - PATCH
      count:
        type: integer
    example:
      href: string
responses:
  '400':
    description: "code    | title                                 \n------- | ------------------------------------- \n477     | INVALID FORMAT\n572     | INVALID OPTION \n2781    | INVALID LENGTH\n4926    | INVALID DATA RECEIVED               \n32171   | MANDATORY DATA MISSING \t     \n"
    schema:
      $ref: '#/definitions/Error_400'
  '404':
    description: Not Found
    schema:
      $ref: '#/definitions/Error_404'
  '500':
    description: Unexpected Error
    schema:
      $ref: '#/definitions/Error_500'
  airport-city-autocomplete:
    description: Successful Operation
    schema:
      title: Success
      required:
        - data
      properties:
        meta:
          $ref: '#/definitions/Collection_Meta'
        data:
          type: array
          items:
            $ref: '#/definitions/Location'
      example:
        meta:
          count: 2
          links:
            self: 'https://test.api.amadeus.com/v1/reference-data/locations?subType=CITY,AIRPORT&keyword=MUC&countryCode=DE'
        data:
          - type: location
            subType: CITY
            name: MUNICH INTERNATIONAL
            detailedName: 'MUNICH/DE:MUNICH INTERNATIONAL'
            id: CMUC
            self:
              href: 'https://test.api.amadeus.com/v1/reference-data/locations/CMUC'
              methods:
                - GET
            timeZoneOffset: '+02:00'
            iataCode: MUC
            geoCode:
              latitude: 48.35378
              longitude: 11.78609
            address:
              cityName: MUNICH
              cityCode: MUC
              countryName: GERMANY
              countryCode: DE
              regionCode: EUROP
            analytics:
              travelers:
                score: 27
          - type: location
            subType: AIRPORT
            name: MUNICH INTERNATIONAL
            detailedName: 'MUNICH/DE:MUNICH INTERNATIONAL'
            id: AMUC
            self:
              href: 'https://test.api.amadeus.com/v1/reference-data/locations/AMUC'
              methods:
                - GET
            timeZoneOffset: '+02:00'
            iataCode: MUC
            geoCode:
              latitude: 48.35378
              longitude: 11.78609
            address:
              cityName: MUNICH
              cityCode: MUC
              countryName: GERMANY
              countryCode: DE
              regionCode: EUROP
            analytics:
              travelers:
                score: 27
  airport-city:
    description: Successful Operation
    schema:
      title: Success
      required:
        - data
      properties:
        meta:
          $ref: '#/definitions/Collection_Meta'
        data:
          $ref: '#/definitions/Location'
      example:
        meta:
          links:
            self: 'https://test.api.amadeus.com/v1/reference-data/locations/CMUC'
        data:
          type: location
          subType: CITY
          name: MUNICH INTERNATIONAL
          detailedName: 'MUNICH/DE:MUNICH INTERNATIONAL'
          id: CMUC
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/CMUC'
            methods:
              - GET
          timeZoneOffset: '+02:00'
          iataCode: MUC
          geoCode:
            latitude: 48.35378
            longitude: 11.78609
          address:
            cityName: MUNICH
            cityCode: MUC
            countryName: GERMANY
            countryCode: DE
            regionCode: EUROP
          analytics:
            travelers:
              score: 27
  400_GET-Id:
    description: |
      code    | title                                 
      ------- | ------------------------------------- 
      572     | INVALID OPTION    
    schema:
      $ref: '#/definitions/Error_400'