swagger: '2.0'
info:
  version: 1.1.2
  title: Points of Interest
  x-tags:
  - '#ama-for-dev'
  x-status: validated
  x-release-note:
    '1.1':
    - 'Add an id, self and rank to location resource'
    - Introduce GET by id
    - add filter parameter for search operation
    1.0.2:
    - New by-square endpoint as secondary resource
    1.0.1:
    - Move from PointOfInterst to Location definition
    '1.0':
    - Initial Version
  description: "\nBefore 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.\n\nPlease also be aware that our test environment is based on a subset of the production, this API in test only returns a few selected cities. You can find the list in our
    **[data collection](https://github.com/amadeus4dev/data-collection)**.\n"
host: test.api.amadeus.com
basePath: /v1
schemes:
- https
consumes:
- application/vnd.amadeus+json
produces:
- application/vnd.amadeus+json
paths:
  /reference-data/locations/pois:
    get:
      tags:
      - Search
      operationId: getPointsOfInterest
      summary: Amadeus Returns Points of Interest for a Given Location and Radius.
      parameters:
      - name: latitude
        description: Latitude (decimal coordinates)
        in: query
        required: true
        type: number
        format: double
        x-example: 41.397158
      - name: longitude
        description: Longitude (decimal coordinates)
        in: query
        required: true
        type: number
        format: double
        x-example: 2.160873
      - name: radius
        description: 'radius of the search in Kilometer. Can be from 0 to 20, default value is 1 Km.'
        in: query
        required: false
        type: integer
        minimum: 0
        maximum: 20
        default: 1
      - $ref: '#/parameters/pageLimit'
      - $ref: '#/parameters/pageOffset'
      - $ref: '#/parameters/categories'
      responses:
        '200':
          $ref: '#/responses/points-of-interest'
        '400':
          $ref: '#/responses/400'
        default:
          $ref: '#/responses/500'
      description: ''
  '/reference-data/locations/pois/{poisId}':
    parameters:
    - $ref: '#/parameters/poisId'
    get:
      tags:
      - Retrieve
      operationId: getPointOfInterest
      summary: Amadeus Retieve One Point of Interest by its Id.
      responses:
        '200':
          $ref: '#/responses/point-of-interest'
        '400':
          $ref: '#/responses/400'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/500'
      description: ''
  /reference-data/locations/pois/by-square:
    get:
      tags:
      - Search
      operationId: getPointsOfInterestBySquare
      summary: Amadeus Returns Points of Interest for a Given Area
      parameters:
      - name: north
        description: Latitude north of bounding box (decimal coordinates)
        in: query
        required: true
        type: number
        format: double
        x-example: 41.397158
      - name: west
        description: Longitude west of bounding box (decimal coordinates)
        in: query
        required: true
        type: number
        format: double
        x-example: 2.160873
      - name: south
        description: Latitude south of bounding box (decimal coordinates)
        in: query
        required: true
        type: number
        format: double
        x-example: 41.394582
      - name: east
        description: Longitude east of bounding box (decimal coordinates)
        in: query
        required: true
        type: number
        format: double
        x-example: 2.177181
      - $ref: '#/parameters/pageLimit'
      - $ref: '#/parameters/pageOffset'
      - $ref: '#/parameters/categories'
      responses:
        '200':
          $ref: '#/responses/points-of-interest'
        '400':
          $ref: '#/responses/400'
        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
  categories:
    name: categories
    description: |
      category of the location. 

      Multiple value can be selected using a comma i.e. SIGHTS, SHOPPING
    in: query
    required: false
    type: array
    items:
      type: string
      enum:
      - SIGHTS
      - NIGHTLIFE
      - RESTAURANT
      - SHOPPING
      collectionFormat: csv
  poisId:
    name: poisId
    description: identifier of the pois
    required: true
    in: path
    type: string
    x-example: 9CB40CB5D0
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
      geoCode:
        $ref: '#/definitions/GeoCode'
      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
  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
  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:
    properties:
      href:
        type: string
        format: uri
      methods:
        type: array
        items:
          type: string
          enum:
          - GET
          - PUT
          - DELETE
          - POST
          - PATCH
    example:
      href: string
responses:
  '400':
    description: "code    | title                                 \n------- | ------------------------------------- \n477     | INVALID FORMAT\n572     | INVALID OPTION\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'
  points-of-interest:
    description: Successful Operation
    schema:
      title: Success
      required:
      - data
      properties:
        meta:
          $ref: '#/definitions/Collection_Meta'
        data:
          type: array
          items:
            $ref: '#/definitions/Location'
      example:
        data:
        - type: location
          subType: POINT_OF_INTEREST
          id: 9CB40CB5D0
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/9CB40CB5D0'
            methods:
            - GET
          geoCode:
            latitude: 41.39165
            longitude: 2.164772
          name: Casa Batlló
          category: SIGHTS
          rank: 5
          tags:
          - sightseeing
          - sights
          - museum
          - landmark
          - tourguide
          - restaurant
          - attraction
          - activities
          - commercialplace
          - shopping
          - souvenir
        - type: location
          subType: POINT_OF_INTEREST
          id: 4690B83DCA
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/4690B83DCA'
            methods:
            - GET
          geoCode:
            latitude: 41.397987
            longitude: 2.161159
          name: La Pepita
          category: RESTAURANT
          rank: 30
          tags:
          - restaurant
          - tapas
          - pub
          - bar
          - sightseeing
          - commercialplace
        - type: location
          subType: POINT_OF_INTEREST
          id: 3EF139D861
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/3EF139D861'
            methods:
            - GET
          geoCode:
            latitude: 41.38827
            longitude: 2.161604
          name: Brunch & Cake
          category: RESTAURANT
          rank: 30
          tags:
          - vegetarian
          - restaurant
          - breakfast
          - shopping
          - bakery
          - transport
          - patio
          - garden
        - type: location
          subType: POINT_OF_INTEREST
          id: AB3F122E3E
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/AB3F122E3E'
            methods:
            - GET
          geoCode:
            latitude: 41.392376
            longitude: 2.160919
          name: Cervecería Catalana
          category: RESTAURANT
          rank: 30
          tags:
          - restaurant
          - tapas
          - sightseeing
          - traditionalcuisine
          - bar
          - activities
          - commercialplace
        - type: location
          subType: POINT_OF_INTEREST
          id: 752402FCA2
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/752402FCA2'
            methods:
            - GET
          geoCode:
            latitude: 41.40043
            longitude: 2.15463
          name: Botafumeiro
          category: RESTAURANT
          rank: 30
          tags:
          - restaurant
          - seafood
          - sightseeing
          - professionalservices
          - transport
          - commercialplace
        - type: location
          subType: POINT_OF_INTEREST
          id: 5F1CED3994
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/5F1CED3994'
            methods:
            - GET
          geoCode:
            latitude: 41.39148
            longitude: 2.164981
          name: Casa Amatller
          category: SIGHTS
          rank: 100
          tags:
          - sightseeing
          - sights
          - museum
          - landmark
          - restaurant
          - tourguide
          - historicplace
          - historic
          - attraction
          - commercialplace
          - activities
          - shopping
          - events
        - type: location
          subType: POINT_OF_INTEREST
          id: 30601A1A90
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/30601A1A90'
            methods:
            - GET
          geoCode:
            latitude: 41.390785
            longitude: 2.167414
          name: Tapas 24
          category: RESTAURANT
          rank: 100
          tags:
          - restaurant
          - tapas
          - traditionalcuisine
          - sightseeing
          - commercialplace
          - transport
          - patio
          - garden
          - activities
          - bar
        - type: location
          subType: POINT_OF_INTEREST
          id: 15C8B8148C
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/15C8B8148C'
            methods:
            - GET
          geoCode:
            latitude: 41.392677
            longitude: 2.153942
          name: Dry Martini
          category: NIGHTLIFE
          rank: 100
          tags:
          - bar
          - restaurant
          - nightlife
          - club
          - sightseeing
          - attraction
          - activities
        - type: location
          subType: POINT_OF_INTEREST
          id: BD29CF2CCD
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/BD29CF2CCD'
            methods:
            - GET
          geoCode:
            latitude: 41.399193
            longitude: 2.159853
          name: Con Gracia
          category: RESTAURANT
          rank: 100
          tags:
          - restaurant
          - sightseeing
          - commercialplace
          - professionalservices
          - activities
        - type: location
          subType: POINT_OF_INTEREST
          id: 24DE6CE737
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/24DE6CE737'
            methods:
            - GET
          geoCode:
            latitude: 41.390198
            longitude: 2.156974
          name: Osmosis
          category: RESTAURANT
          rank: 100
          tags:
          - restaurant
          - shopping
          - transport
          - professionalservices
        meta:
          count: 120
          links:
            self: 'https://test.api.amadeus.com/v1/reference-data/locations/pois?latitude=41.397158&longitude=2.160873'
            next: 'https://test.api.amadeus.com/v1/reference-data/locations/pois?latitude=41.397158&longitude=2.160873&page[offset]=10&page[limit]=10'
            last: 'https://test.api.amadeus.com/v1/reference-data/locations/pois?latitude=41.397158&longitude=2.160873&page[offset]=120&page[limit]=10'
            first: 'https://test.api.amadeus.com/v1/reference-data/locations/pois?latitude=41.397158&longitude=2.160873&page[offset]=0&page[limit]=10'
            up: 'https://test.api.amadeus.com/v1/reference-data/locations/pois?latitude=41.397158&longitude=2.160873'
  point-of-interest:
    description: Successful Operation
    schema:
      title: Success
      required:
      - data
      properties:
        meta:
          $ref: '#/definitions/Collection_Meta'
        data:
          $ref: '#/definitions/Location'
      example:
        data:
          type: location
          subType: POINT_OF_INTEREST
          id: 9CB40CB5D0
          self:
            href: 'https://test.api.amadeus.com/v1/reference-data/locations/pois/9CB40CB5D0'
            methods:
            - GET
          geoCode:
            latitude: 41.39165
            longitude: 2.164772
          name: Casa Batlló
          category: SIGHTS
          rank: 1
          tags:
          - sightseeing
          - sights
          - museum
          - landmark
          - tourguide
          - restaurant
          - attraction
          - activities
          - commercialplace
          - shopping
          - souvenir
x-generatedAt: '2020-07-22T12:31:24.740Z'