openapi: "3.0.0"
info:
  title: "Congestion API"
  version: "1.1.1"
  description: Welcome to the documentation of the Congestion API
    
    <h1>Compatibility guidelines</h1>
    <p>The HTTP API is versioned with a single number, which is currently 1</p>
    <p>This number symbolizes the major version number. New features can be added to the API in the same version number if there is no breaking change.</p>
    <p>The version number is present in the url, for instance <strong>/congestion/api/v1</strong> for the current version.
    
    <h1>Documentation, Pricing and Key generation</h1>
    <p>You can find the complete documentation for our API at <a href='https://developers.sinay.ai/'>Developers Platform</a>.</p>
    <p>Create an account to receive your FREE key in under a minute!</p>
    <p>Additionally, explore our pricing plans, access support, view detailed documentation, and follow our comprehensive tutorials.</p>

    <h1>Authentication</h1>
    <p>Every endpoints of this API require authentication using an API key.</p>
    <p>If you don't have an API Key and you need to use the Congestion API, you need to ask Sinay to have one.</p>
    <p>To use the API Key, you must add a header named <strong>API_KEY</strong> with your API Key as a value.</p>
    <h1>Test the API with Swagger-ui</h1>
    <p>To test the API using Swagger-ui, you must click on the button <strong>Authorize</strong> and then fill the <strong>apiKey</strong> field and click on <strong>Authorize</strong>.</p>
    <p>Swagger-ui will then use the api key automatically in each request.</p>
    <p>On every endpoints, you can click on <strong>Try it out</strong>, you can modify the body
    and then click on <strong>Execute</strong></p>
    <p>You will be able to see the response.</p>
  
    <h1>Release note</h1>
    <h2>1.0.0</h2>
    <ul>
    </ul>
servers:
  - url: "https://api.sinay.ai/congestion/api/v1"
tags:
  - name: Congestion
    description: Endpoint that allow you to retrieve the congestion in a port
  - name: Consumption
    description: Endpoints that allow you to retrieve your credit consumption
paths:
  "/congestion/{portCode}":
    get:
      operationId: "retrieveCongestionAggregate"
      summary: "Retrieve aggregated congestion data for a port"
      description:
        <p>Returns congestion, time-in-port statistics, and vessel counts for a given port.</p>
      tags:
        - Congestion
      parameters:
        - $ref: '#/components/parameters/portCodePath'
      responses:
        '200':
          description: "The congestion aggregate"
          headers:
            X-Request-Id:
              description: An unique id to trace request accross system
              schema:
                type: string
                example: 6c85ead8-466e-4779-ab9d-15a7e98a0d54
            X-Resource-Type:
              description: The type of resource returned
              schema:
                type: string
                example: PORT_CONGESTION
            X-Requested-Count:
              description: Number of ports requested
              schema:
                type: integer
            X-Found-Count:
              description: Number of ports for which data was found
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/congestionAggregate'
              example:
                portCode: FRLEH
                rateOccupation:
                  commercialVessels:
                    rateOccupationPercentage: 28.57
                    rateOccupationGapWithMean: -25.0
                  cargo:
                    rateOccupationPercentage: 32.92
                    rateOccupationGapWithMean: -1.69
                  tanker: null
                  roro: null
                time:
                  timeInPortStatistics:
                    max: 89.02
                    median: 56.39
                    min: 23.76
                vesselsInPortCount:
                  commercialVessels: 8
                  cargo: 8
                  tanker: 0
                  roro: 0
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
        default:
          $ref: '#/components/responses/default'
  "/congestion/batch":
    post:
      operationId: "retrieveCongestionAggregateBatch"
      summary: "Retrieve aggregated congestion data for multiple ports"
      description:
        <p>Returns congestion, time-in-port statistics, and vessel counts for a list of ports.</p>
        <p>Maximum 10 ports per request.</p>
      tags:
        - Congestion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/congestionBatchRequest'
            example:
              portCodes:
                - FRMRS
                - FRLEH
      responses:
        '200':
          description: "The congestion aggregates"
          headers:
              X-Request-Id:
                description: An unique id to trace request accross system
                schema:
                  type: string
                  example: 6c85ead8-466e-4779-ab9d-15a7e98a0d54
              X-Resource-Type:
                description: The type of resource returned
                schema:
                  type: string
                  example: PORT_CONGESTION
              X-Requested-Count:
                description: Number of ports requested
                schema:
                  type: integer
              X-Found-Count:
                description: Number of ports for which data was found
                schema:
                  type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/congestionAggregate'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/internalServerError'
        default:
          $ref: '#/components/responses/default'
  "/consumption/current-period":
    get:
      operationId: "retrieveCurrentConsumptionPeriod"
      summary: "Retrieve the current credit consumption period"
      tags:
        - Consumption
      responses:
        '200':
          description: "The current consumption period"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consumptionPeriod'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
        default:
          $ref: '#/components/responses/default'
  "/consumption/periods":
    get:
      operationId: "retrieveConsumptionPeriods"
      summary: "Retrieve all credit consumption periods"
      tags:
        - Consumption
      responses:
        '200':
          description: "The consumption periods"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/consumptionPeriod'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/internalServerError'
        default:
          $ref: '#/components/responses/default'
components:
  schemas:
    congestionBatchRequest:
      type: object
      required:
        - portCodes
      properties:
        portCodes:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 10
          description: List of port codes (unlocode), maximum 10

    congestionAggregate:
      type: object
      required:
        - portCode
        - rateOccupation
        - time
        - vesselsInPortCount
      properties:
        portCode:
          type: string
          description: The port code (unlocode)
        rateOccupation:
          $ref: '#/components/schemas/rateOccupationBreakdown'
        time:
          $ref: '#/components/schemas/timeAggregate'
        vesselsInPortCount:
          $ref: '#/components/schemas/vesselsInPortCount'

    rateOccupationBreakdown:
      type: object
      properties:
        commercialVessels:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/rateOccupationByVesselType'
        cargo:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/rateOccupationByVesselType'
        tanker:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/rateOccupationByVesselType'
        roro:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/rateOccupationByVesselType'

    rateOccupationByVesselType:
      type: object
      properties:
        rateOccupationPercentage:
          type: number
          format: double
          nullable: true
        rateOccupationGapWithMean:
          type: number
          format: double
          nullable: true

    timeAggregate:
      type: object
      properties:
        timeInPortStatistics:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/timeStatistics'

    timeStatistics:
      type: object
      properties:
        max:
          type: number
          format: double
          nullable: true
        median:
          type: number
          format: double
          nullable: true
        min:
          type: number
          format: double
          nullable: true

    vesselsInPortCount:
      type: object
      properties:
        commercialVessels:
          type: integer
          nullable: true
        cargo:
          type: integer
          nullable: true
        tanker:
          type: integer
          nullable: true
        roro:
          type: integer
          nullable: true

    consumptionPeriod:
      type: object
      required:
        - id
        - credits
        - creditsInitial
        - periodStart
        - periodEnd
        - expired
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the consumption period
        credits:
          type: integer
          description: Remaining credits
        creditsInitial:
          type: integer
          description: Credits allocated at the start of the period
        periodStart:
          type: string
          format: date-time
          description: Start of the period
        periodEnd:
          type: string
          format: date-time
          description: End of the period
        expired:
          type: boolean
          description: Whether this period has expired
      example:
        id: "091c4dc8-e979-4607-b9ca-78260ab48dfe"
        credits: 3
        creditsInitial: 3
        periodStart: "2024-10-21T11:20:17Z"
        periodEnd: "2224-10-21T11:20:17Z"
        expired: false

    errorInfo:
      type: object
      required:
        - errorCode
        - message
        - details
        - time
      properties:
        errorCode:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            type: string
        time:
          type: string
          format: date-time
  parameters:
    portCodePath:
      in: path
      name: portCode
      required: true
      schema:
        type: string
      description: The port code (unlocode) of the port
  responses:
    badRequest:
      description: The body in the request is not correct
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    internalServerError:
      description: An error occurend on server side
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    notFound:
      description: The resource has not been found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    unauthorized:
      description: The authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    default:
      description: default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API_KEY
security:
  - ApiKey: [ ]