openapi: "3.0.0"
info:
  title: "API Noise emission"
  version: "1.1.1"
  description: Welcome to the documentation of the Noise API
    
    <h1>Compatibility guidelines</h1>
    <p>The HTTP API is versioned with a single number, which is currently 1</p>
    <p>The first 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>/noise/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 Noise emission 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>
    <li>Noise computation (SEL and thresholds comparisons) for a vessel from a port to another port</li>
    </ul>
servers:
  - url: "https://api.sinay.ai/noise/api/v1/"
tags:
  - name: Noise computation
    description: Endpoint that allows you to compute the SEL and noises emission in multiple frequencies of a vessel for a trip from a port to another port and compare them to the recommended thresholds.
paths:
  "/compute-noise":
    post:
      operationId: "computeNoise"
      summary: Retrieve Noise emitted for a trip from one port to another.
      tags:
        - Noise computation
      description:
        <p>This endpoint is used to compute the SEL and noises emissions in multiple frequencies of a vessel during its journey from a port to another port and compare them to the recommended thresholds.</p>
        <h2>Request</h2>
        <h3>Vessel</h3>
        <p>To identify the vessel, you can use the IMO (International Maritime Organization) or the MMSI (Maritime Mobile Service Identity).</p>
        <h3>Departure</h3>
        <p>You can set up the departure port using its 5 digits UN Locode. Please make sure it is a Locode for a port.</p>
        <h3>Arrival</h3>
        <p>You can set up the arrival port using its 5 digits UN Locode. Please make sure it is a Locode for a port.</p>
        <h2>Response</h2>
        <p>The response will give you an estimation of the SEL and booleans indicating if the noise emitted is above the recommended thresholds for this voyage.</p>
        <p>To achieve this result, we model the journey from port to port of this vessel using our data models. We also use our database of ships to model their physical characteristics to estimate their emission of noise.</p>
        <h3>Duration</h3>
        <p>The duration response is in milliseconds (ms).</p>
        <h3>SEL</h3>
        <p>The sel response is in pascal squared second (Pa².s).</p>

      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/computeNoiseRequest"
            examples:
              noise:
                summary: "Compute Noise"
                value:
                  vessel:
                    imo: 9706906
                  departure:
                    portCode: "FRLEH"
                  arrival:
                    portCode: "ESBCN"
      responses:
        '200':
          description:
            <p>Successful Response</p>
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/computeNoiseResponse"
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/errorInfo"
  "/usages":
    get:
      parameters:
        - $ref: '#/components/parameters/usageStartTime'
        - $ref: '#/components/parameters/usageEndTime'
      operationId: "retrieveUsages"
      summary: "Retrieve your monthly usages"
      description:
        <p>The endpoint allows you to retrieve your monthly usages of the API</p>
      tags:
        - Usage
      responses:
        '200':
          description: "The monthly usages"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usagesResponse'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/internalServerError'
        default:
          $ref: '#/components/responses/default'
components:
  schemas:
    usagesResponse:
      type: object
      required:
        - allCalls
        - successCalls
        - clientErrorCalls
        - serverErrorCalls
        - consumedApiUnits
      properties:
        allCalls:
          $ref: '#/components/schemas/numberOfCalls'
        successCalls:
          $ref: '#/components/schemas/numberOfCalls'
        clientErrorCalls:
          $ref: '#/components/schemas/numberOfCalls'
        serverErrorCalls:
          $ref: '#/components/schemas/numberOfCalls'
        consumedApiUnits:
          $ref: '#/components/schemas/numberOfCalls'
        periodicUsages:
          $ref: '#/components/schemas/periodicUsages'
      example:
        allCalls: 15
        successCalls: 13
        clientErrorCalls: 1
        serverErrorCalls: 1
        consumedApiUnits: 25
        periodicUsages:
          2022-05:
            allCalls: 15
            successCalls: 13
            clientErrorCalls: 1
            serverErrorCalls: 1
            consumedApiUnits: 25
    periodicUsages:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/periodicUsage'
    periodicUsage:
      type: object
      required:
        - allCalls
        - successCalls
        - clientErrorCalls
        - serverErrorCalls
        - consumedApiUnits
      properties:
        allCalls:
          $ref: '#/components/schemas/numberOfCalls'
        successCalls:
          $ref: '#/components/schemas/numberOfCalls'
        clientErrorCalls:
          $ref: '#/components/schemas/numberOfCalls'
        serverErrorCalls:
          $ref: '#/components/schemas/numberOfCalls'
        consumedApiUnits:
          $ref: '#/components/schemas/numberOfCalls'
    numberOfCalls:
      type: integer
      format: int64
    computeNoiseRequest:
      type: object
      required:
        - departure
        - arrival
        - vessel
      properties:
        departure:
          description: "departure information for noise request"
          allOf:
            - $ref: "#/components/schemas/noisePort"
        vessel:
          description: "Vessel information for noise request"
          allOf:
            - $ref: "#/components/schemas/noiseVessel"
        arrival:
          description: "arrival info for noise request"
          allOf:
            - $ref: "#/components/schemas/noisePort"
    noiseVessel:
      type: object
      maxProperties: 1
      minProperties: 1
      properties:
        imo:
          type: integer
          format: int64
          description: "mmsi vessel information"
        mmsi:
          type: integer
          format: int64
          description: "imo vessel information"
    noisePort:
      type: object
      required:
        - portCode
      properties:
        portCode:
          type: string
          description: "Port code"
    computeNoiseResponse:
      description: "noise response from computing"
      type: object
      properties:
        input:
          allOf:
            - $ref: '#/components/schemas/computeNoiseRequest'
        sel:
          type: number
          format: double
        duration:
          type: integer
          format: int32
        isAboveRecommendedThresholds:
          type: object
          properties:
            LloydsTransit:
              type: boolean
            BureauVeritasStandard:
              type: boolean
      example:
        input:
          vessel:
            imo: 9706906
          departure:
            portCode: FRLEH
          arrival:
            portCode: ESBCN
        sel: 264.982187824978
        duration: 455088169
        isAboveRecommendedThresholds:
          LloydsTransit: true
          BureauVeritasStandard: 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:
    usageStartTime:
      in: query
      name: startTime
      required: false
      schema:
        type: string
        format: date-time
      description: Start time at which usages must be found
    usageEndTime:
      in: query
      name: endTime
      required: false
      schema:
        type: string
        format: date-time
      description: End time at which usages must be found
  responses:
    badRequest:
      description: The body in the request is not correct
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    internalServerError:
      description: An error occurred 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'
    conflict:
      description: The resource already exists
      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: [ ]