openapi: "3.0.0"
info:
  title: "ETAC API"
  description: Welcome to the documentation of the ETAC 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>/etac/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 ETAC 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.3.1</h2>
    <ul>
    <li>Added distance in ETA response</li>
    </ul>
    <h2>1.3.0</h2>
    <ul>
    <li>Removed ETA computation from position to port</li>
    </ul>
    <h2>1.2.0</h2>
    <ul>
    <li>Added usages endpoint</li>
    </ul>
    <h2>1.1.0</h2>
    <ul>
    <li>Added speed of the vessel in input</li>
    <li>Added confidence in response</li>
    </ul>
    <h2>1.0.0</h2>
    <ul>
    <li>Eta computation from port to port, from vessel position to port and from position to port</li>
    <li>Authentication using api key</li>
    </ul>
  version: "1.5.2"
servers:
  - url: "https://api.sinay.ai/etac/api/v1"
tags:
  - name: Estimated time arrival
    description: Endpoint that allow you to compute the eta of a vessel
  - name: Usage
    description: Endpoints that allow you to retrieve your api usages
paths:
  "/compute-eta":
    post:
      operationId: "computeEta"
      summary: "ETA computation"
      description:
        <p>This endpoint is used to compute the Estimated Time of Arrival of any vessel.</p>
        <h1>Request</h1>
        <p>To compute the ETA of a vessel, we need information concerning the vessel, the departure (optional)
        and the arrival. These 3 elements are present in the request in 3 different fields.</p>
        <p>It will allow you to compute the ETA of a vessel <strong>from the vessel position to a port</strong> or <strong>from a port to another port</strong>.</p>
        <h2>Vessel</h2>
        <p>To identify the vessel, you can use the IMO (International Maritime Organization) or the MMSI (Maritime Mobile Service Identity).</p>
        <p>You can optionally set the vessel speed to use for computation, in nautical miles per hour. The maximum speed is 25.0</p>
        <h2>Departure</h2>
        <p>By default, the ETA is computed with the latest known position of the vessel as departure (time and position). The API allows you to compute an ETA of a vessel from a port to another port.
        In that case, you must use the field <strong>departure</strong> to define the departure port code and the departure date time (ISO 8601 format).</p>
        <p><strong>Note that you can't define a departure date time in case of vessel position to port ETA computation.</strong></p>
        <h2>Arrival</h2>
        <p>Arrival field is used to define to where the eta must be computed. You need to indicate the port code of the arrival.
        <h1>Response</h1>
        <p>You will find the response of the ETA in the field named <strong>arrivalTime</strong> in format
        ISO 8601</p>
        <p>You will also find the confidence of the result which is a value from 1 to 5, 5 means high confidence.</p>
        <p>You will also find the remaining distance which is in nautical miles</p>
        <p>The fields from the request will also be added in the response.</p>
        <h1>Examples</h1>
        <p>You can find below 2 examples of payloads for the 2 ways to compute the ETA.</p>
      tags:
        - Estimated time arrival
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/etaRequest'
            examples:
              vesselPositionToPort:
                summary: "Vessel position to port"
                description: "Our API will automatically select the latest AIS transmitted position as a departure point and date"
                value:
                  vessel:
                    imo: 9706906
                  arrival:
                    portCode: "FRLEH"
              portToPort:
                summary: "Port to port"
                description: " The ETA will be computed using the departure portCode and departure date as departure and the arrival PortCode as arrival port."
                value:
                  vessel:
                    imo: 9706906
                  departure:
                    date: "2020-01-10T10:00:00.000Z"
                    portCode: "FRLEH"
                  arrival:
                    portCode: "ESBCN"
      responses:
        '200':
          description: "The computed ETA"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/etaResponse'
        '401':
          $ref: '#/components/responses/unauthorized'
        '400':
          $ref: '#/components/responses/badRequest'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
        default:
          $ref: '#/components/responses/default'
  "/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
    etaRequest:
      type: object
      required:
        - vessel
        - arrival
      properties:
        vessel:
          $ref: '#/components/schemas/etaVessel'
        departure:
          $ref: '#/components/schemas/etaDeparture'
        arrival:
          $ref: '#/components/schemas/etaArrival'
      x-examples:
        vesselPositionToPort:
          summary: "Vessel position to port"
          value:
            vessel:
              imo: 222222
            arrival:
              portCode: "FRLEH"
        portToPort:
          summary: "Port to port"
          description: "The ETA will be computed using the departure portCode as departure and the arrivalPortCode as arrival portCode"
          value:
            vessel:
              imo: 111111
            departure:
              date: "2020-01-10T10:00:00.000Z"
              portCode: "FRLEH"
            arrival:
              portCode: "ESBCN"
    etaVessel:
      type: object
      properties:
        imo:
          $ref: '#/components/schemas/etaImo'
        mmsi:
          $ref: '#/components/schemas/etaMmsi'
        speed:
          $ref: '#/components/schemas/etaSpeed'
    etaSpeed:
      type: number
      format: double
      minimum: 0.0
      maximum: 25.0
      description: The speed of the vessel you want to use in the eta computation, in nautical mile per hour
    etaImo:
      type: integer
      format: int64
    etaMmsi:
      type: integer
      format: int64
    etaDeparture:
      type: object
      properties:
        date:
          $ref: '#/components/schemas/departureDate'
        portCode:
          $ref: '#/components/schemas/departurePortCode'
    departureDate:
      type: string
      format: date-time
      description: "Date-time of departure, if not present, the current date-time (now) will be used"
    departurePortCode:
      type: string
      pattern: '^(A[D-GILMOQ-UWXZ]|B[ABIE-HDJLM-OQR-TWYZ]|C[ACDF-IK-ORU-Z]|D[EJKMOZ]|E[CEGHRST]|F[I-KMOR]|JE|G[ABD-IL-UWY]|H[KMNRTU]|I[DELMNOQRST]|J[MOP]|K[EGHIMNPRWY]|K[YZ]|L[ABCIKR-VY]|M[AC-HKL-Z]|N[ACE-ILO-PRUZ]|OM|[P-Z][A-Z]+)[A-Z0-9]{3}$'
      description: "The departure port code composed of 5 characters (2 for the country, 3 for the port), if not present neither latitude and latitude, the vessel position will be used"
    etaArrival:
      type: object
      required:
        - portCode
      properties:
        portCode:
          $ref: '#/components/schemas/arrivalPortCode'
    arrivalPortCode:
      type: string
      pattern: '^(A[D-GILMOQ-UWXZ]|B[ABIE-HDJLM-OQR-TWYZ]|C[ACDF-IK-ORU-Z]|D[EJKMOZ]|E[CEGHRST]|F[I-KMOR]|JE|G[ABD-IL-UWY]|H[KMNRTU]|I[DELMNOQRST]|J[MOP]|K[EGHIMNPRWY]|K[YZ]|L[ABCIKR-VY]|M[AC-HKL-Z]|N[ACE-ILO-PRUZ]|OM|[P-Z][A-Z]+)[A-Z0-9]{3}$'
      description: "Arrival port code composed of 5 characters (2 for the country, 3 for the port)"
    etaResponse:
      type: object
      required:
        - arrivalTime
        - confidence
        - vessel
        - arrival
      properties:
        arrivalTime:
          $ref: '#/components/schemas/etaArrivalTime'
        vessel:
          $ref: '#/components/schemas/etaVessel'
        departure:
          $ref: '#/components/schemas/etaDeparture'
        arrival:
          $ref: '#/components/schemas/etaArrival'
        confidence:
          $ref: '#/components/schemas/etaConfidence'
        remainingTime:
          $ref: '#/components/schemas/etaRemainingTime'
        errorMarginValue:
          $ref: '#/components/schemas/etaErrorMarginValue'
        remainingDistance:
          $ref: '#/components/schemas/etaRemainingDistance'
      example:
        arrivalTime: "2022-01-11T12:00:00.000Z"
        confidence: 3
        etaRemainingTime: 540.0
        etaErrorMarginValue: 140.4
        vessel:
          imo: 111111
          speed: 12.5
        departure:
          date: "2020-01-10T10:00:00.000Z"
          portCode: "FRLEH"
        arrival:
          portCode: "ESBCN"
        remainingDistance: 1250.0
    etaRemainingDistance:
      type: number
      format: double
      description: The remaining distance in nautical miles
    etaArrivalTime:
      type: string
      format: date-time
      description: The time at which the vessel will arrive
    etaRemainingTime:
      type: number
      format: double
      description: "Predicted remaining time in hours."
    etaErrorMarginValue:
      type: number
      format: double
      description: "Error margin value in hours."
    etaConfidence:
      type: integer
      format: int32
      minimum: 1
      maximum: 5
      description: The confidence of the eta computation, from 1 (low confidence) to 5 (high confidence)
    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 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: [ ]