openapi: 3.0.0
info:
  title: Vodafone Analytics Reference QuadKey
  description: >-
    This API is specifically built for Vodafone Analtyics (VFA) to support the
    resolution of points of interest expressed in latitude and longitude to a
    QuadKey tile ID.
  # contact:
  #   email: luispedro.oliveira@vodafone.com
  # license:
  #   name: Apache 2.0
  #   url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  version: 1.1.0
servers:

  - url: https://api-sandbox.vf-dmp.engineering.vodafone.com/vfAnalytics/referenceQuadkey/v1
    description: "Sandbox"
  #- url: https://api.vf-dmp.engineering.vodafone.com/vfAnalytics/referenceQuadkey/v1
  # description: "Production"

paths:
  /xyToQuadkey:
    post:
      tags:
        - Vodafone Analytics Reference QuadKey
      summary: >-
        This API provides a QuadKey tile ID for the latitude, longitude and zoom
        level specified
      operationId: xyToQuadkey
      parameters:
        - name: vf_ext_bp_id
          in: header
          description: A unique use case ID used for logging and end-to-end tracing.
          schema:
            type: string
          example: 
        - name: X-Correlator
          in: header
          description: >-
            Correlation UUID that will be included in the response to request.
          schema:
            type: string
          required: false
          example: 988c911a-92d4-11e7-abc4-cec278b6b50a
        - name: vf-country-code
          in: header
          description: ISO 3166-1 alpha-2 Country Code.
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 2
          example: GB
      requestBody:
        required: true
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/xyToQuadkeyRequest'
      responses:
        '200':
          description: The request to convert to a quadkey was handled successfully
          headers:
            X-Correlator:
              $ref: '#/components/headers/X-Correlator'

            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Expires:
              $ref: '#/components/headers/Expires'
            Date:
              $ref: '#/components/headers/Date'
            Pragma:
              $ref: '#/components/headers/Pragma'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
          content:
            application/json:
              schema:
                type: object
                description: Response for the corresponding individual request
                required:
                  - quadkeyId
                properties:
                  quadkeyId:
                    type: string
                    description: >-
                      The quadkey ID of the tile that contains the specified
                      point
                    example: '12020020200001'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'

      security:
        - apixClientCredentials:
            - VF_ANALYTICS_REFERENCE_QUADKEY_ALL
  /shapeToQuadkeys:
    post:
      tags:
        - Vodafone Analytics Reference QuadKey
      summary: >-
        API returns all the intersecting quadkeys for a given WKTPolygon shape
        and quadkey zoom level
      operationId: shapeToQuadkeys
      parameters:
        - name: vf_ext_bp_id
          in: header
          description: A unique use case ID used for logging and end-to-end tracing.
          schema:
            type: string
          example: 
        - name: X-Correlator
          in: header
          description: >-
            Correlation UUID that will be included in the response to request.
          schema:
            type: string
          required: false
          example: 988c911a-92d4-11e7-abc4-cec278b6b50a
        - name: vf-country-code
          in: header
          description: ISO 3166-1 alpha-2 Country Code.
          required: false
          schema:
            type: string
          example: GB
      requestBody:
        required: true
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/shapeToQuadkeysRequest'
      responses:
        '200':
          description: The request to convert to a quadkey was handled successfully
          headers:
            X-Correlator:
              $ref: '#/components/headers/X-Correlator'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Expires:
              $ref: '#/components/headers/Expires'
            Date:
              $ref: '#/components/headers/Date'
            Pragma:
              $ref: '#/components/headers/Pragma'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
          content:
            application/json:
              schema:
                properties:
                  quadkeyIds:
                    type: array
                    items:
                      type: string
                      description: The quadkey IDs that intersect the specified polygon
                    example:
                      - '12020020200001'
                      - '12020020200000'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
      security:
        - apixClientCredentials:
            - VF_ANALYTICS_REFERENCE_QUADKEY_ALL
  /quadkeyToPolygon:
    post:
      tags:
        - Vodafone Analytics Reference QuadKey
      summary: >-
        API to return a WKT formatted polygon defining the bounding box for a
        specified Quadkey ID
      operationId: quadkeyToPolygon
      parameters:
        - name: vf_ext_bp_id
          in: header
          description: A unique use case ID used for logging and end-to-end tracing.
          schema:
            type: string
          example: 
        - name: X-Correlator
          in: header
          description: >-
            Correlation UUID that will be included in the response to request.
          schema:
            type: string
          required: false
          example: 988c911a-92d4-11e7-abc4-cec278b6b50a
        - name: vf-country-code
          in: header
          description: ISO 3166-1 alpha-2 Country Code.
          required: false
          schema:
            type: string
          example: GB
      requestBody:
        required: true
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/quadkeyToPolygonRequest'
      responses:
        '200':
          description: The request to convert to a quadkey was handled successfully
          headers: 
            X-Correlator:
              $ref: '#/components/headers/X-Correlator'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Expires:
              $ref: '#/components/headers/Expires'
            Date:
              $ref: '#/components/headers/Date'
            Pragma:
              $ref: '#/components/headers/Pragma'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
          content:
            application/json:
              schema:
                type: object
                description: Response for the corresponding individual request
                properties:
                  polygon:
                    type: string
                    minLength: 1
                    description: The WKT formatted polygon for the specified quadkey
                    example: >-
                      POLYGON((-2.694 52.417,-2.219 52.515,-1.755 52.444,-1.623
                      52.067,-2.013 51.888,-2.425 51.942,-2.738 52.144,-2.694
                      52.417))
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
      security:
        - apixClientCredentials:
            - VF_ANALYTICS_REFERENCE_QUADKEY_ALL

  /ping:
    get:
      tags:
        - Monitoring
      summary: Check the upstream system is up and running.
      description: |-
        This API is to check the upstream system is up and running.

      security:
        - apixClientCredentials: []

      operationId: getPing

      parameters:
        - $ref: "#/components/parameters/X-Correlator"

      responses:
        "200":
          description: "**OK**"
          content:
            application/json:
              examples:
                success_response:
                  value: {
                            "suffix": "/ping",
                            "client": "35.191.13.203",
                            "startTime": "2023-06-05T19:47:16.794Z",
                            "endTime": "2023-06-05T19:47:16.888Z",
                            "responseTime": 94,
                            "message": "PONG"
                          }
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
 
  /status:
    get:
      tags:
        - Monitoring
      summary: Check the downstream system is up and running.
      description: |-
        This API is to check the downstream system is up and running.

      security:
        - apixClientCredentials: []

      operationId: getStatus

      parameters:
        - $ref: "#/components/parameters/X-Correlator"

      responses:
        "200":
          description: "**OK**"
          content:
            application/json:
              examples:
                success_response:
                  value: {
                            "status": "OK",

                          }
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'


components:
  responses:
   ############## Added Camara Error Structure ###########################################
   
    Generic400:
      description: |
        **Bad Request**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            invalid argument:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param
    Generic401:
      description: |
        **Unauthorized**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            invalid creds:
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials
    Generic403:
      description: |
        **Forbidden**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            permission denied:
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action
    Generic404:
      description: |
        **Not Found**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:

              NOT_FOUND:
                value: {
                          "status": 404,
                          "code" : "NOT_FOUND",
                          "message": "The specified resource is not found."
                        }
              UNKNOWN_PHONE_NUMBER:
                value: {
                          "status": 404,
                          "code" : "UNKNOWN_PHONE_NUMBER",
                          "message": "Can't be checked because the phone number is unknown."
                        }
    Generic405:
      description: |
        **Method Not Allowed**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            METHOD_NOT_ALLOWED:
              value:
                status: 405
                code: METHOD_NOT_ALLOWED
                message: The requested method is not allowed/supported on
                      the target resource"
    Generic406:
      description: |
        **Not Acceptable**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Not Acceptable:
              value:
                status: 406
                code: Not Acceptable
                message: The server cannot produce a response matching
                          the content requested by the client through Accept-* headers."
    Generic409:
      description: |
        **Conflict**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:

              CONFLICT:
                value: {
                          "status": 409,
                          "code" : "CONFLICT",
                          "message": "The specified resource duplicate entry found."
                        }
              ALREADY_EXISTS:
                value: {
                          "status": 404,
                          "code" : "ALREADY_EXISTS",
                          "message": "The specified resource that client tried to create already exists."
                        }
    Generic415:
      description: |
        **Unsupported Media Type**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            UNSUPPORTED_MEDIA_TYPE:
              value:
                status: 415
                code: UNSUPPORTED_MEDIA_TYPE
                message: The server refuses to accept the request because
                      the payload format is in an unsupported format
    Generic429:
      description: |
        **Too Many Requests**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
              SpikeArrestViolation:
                value: {
                          "status": 429,
                          "code" : "TOO_MANY_REQUESTS",
                          "message": "Spike Arrest Violation."
                        }
              QuotaViolation:
                value: {
                          "status": 429,
                          "code" : "TOO_MANY_REQUESTS",
                          "message": "API/App/Country Quota limit reached."
                        }
    Generic500:
      description: |
        **Internal Server Error**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Internal_Server_Error:
              value:
                status: 500
                code: INTERNAL
                message: The server encountered an unexpected condition
                      that prevented it from fulfilling the request
    Generic502:
      description: |
        **Bad Gateway**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Bad_Gateway:
              value:
                status: 502
                code: BAD_GATEWAY
                message: An upstream internal service cannot be reached
    Generic503:
      description: |
        **UNAVAILABLE**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            UNAVAILABLE:
              value:
                status: 503
                code: UNAVAILABLE
                message: Request timeout exceeded
    Generic504:
      description: |
        **Gateway Timeout**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            TIMEOUT:
              value:
                status: 504
                code: TIMEOUT
                message: Request timeout exceeded. 
            
   
   
####################################################################################################################   
   
   
  schemas:
  
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description

    xyToQuadkeyRequest:
      required:
        - latitude
        - longitude
        - level
      type: object
      properties:
        latitude:
          type: number
          minLength: 1
          minimum: -90
          maximum: 90
          example: 0.1246
          description: Latitude coordinates
        longitude:
          type: number
          minLength: 1
          minimum: -180
          maximum: 180
          example: 51.5007
          description: Longitude coordinate
        level:
          type: integer
          minLength: 1
          minimum: 1
          maximum: 21
          example: 17
          description: Zoom level specified
    shapeToQuadkeysRequest:
      required:
        - polygon
        - level
      type: object
      properties:
        polygon:
          type: string
          minLength: 1
          description: >-
            WKT Formatted Polygon containing WGS84 latitude and longitude points
            (closed, ie start and end points match to be valid)
          example:  POLYGON ((-1.3209514204278 51.4167567391622,-1.32031209555017 51.4172431820039,-1.31976311005741 51.4172779279211,-1.31942954925169 51.4170833507845,-1.31887361457549 51.4159853797989,-1.31879022437406 51.4156518189932,-1.31885276702513 51.4150541892163,-1.31863039315465 51.4143453725041,-1.3191932770143 51.4142480839358,-1.31988124617611 51.4145607971912,-1.32041633330195 51.4146511365761,-1.32029124799981 51.4152765630868,-1.32077769084149 51.4159575830651,-1.32097921716161 51.4167011456946,-1.3209514204278 51.4167567391622))
        level:
          type: integer
          minimum: 1
          maximum: 21
          example: 18
          description: Zoom level specified
    quadkeyToPolygonRequest:
      required:
        - quadkeyId
      type: object
      properties:
        quadkeyId:
          type: string
          minLength: 1
          description: Quadkey ID to be processed
          example: '12020020200001'
  parameters:
    X-Correlator:
      in: header
      name: X-Correlator
      description: "Correlation UUID that will be included in the response to request."
      required: false
      schema:
        type: string
        example: 998c911a-92d4-11e7-abc4-cec278b6b50a
  headers:
  
    X-Correlator:
      description: "Correlation UUID that will be included in the response to request."
      schema:
        type: string

    vf-trace-transaction-id:
      description: "A unique transaction ID. If provided, the same value is\r\n returned, Otherwise a new transaction id is generated and returned by APIX"
      schema:
        type: string
    Cache-Control:
      description: >-
        Must be forwarded from backend response. Otherwise set to default value
        "no-store"
      schema:
        type: string
    Expires:
      description: >-
        ust be forwarded from backend response. Otherwise set to current date
        and time (such as "Sun, 06 Nov 1994 08:49:37 GM")
      schema:
        type: string
    Date:
      description: >-
        Must be forwarded from backend response. Otherwise set to current date
        and time e.g. Sun, 06 Nov 1994 08:49:37 GM
      schema:
        type: string
    Pragma:
      description: to be picked from the backend if available otherwise set as "no-cache"
      schema:
        type: string
    Content-Type:
      description: application/json
      schema:
        type: string
  securitySchemes:
    apixClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth2/v1/token
          scopes:
            VF_ANALYTICS_REFERENCE_QUADKEY_ALL: Allows a client to be able to access to all the resources
