openapi: "3.0.0"
info:
  title: "API CO2 emission"
  version: "2.3.2"
  description: Welcome to the documentation of the CO2 API
    <h1>Compatibility guidelines</h1>
    <p>The HTTP API is versioned with a single number, which is currently 2</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>/co2/api/v2</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 CO2 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>2.3.0</h2>
    <ul>
    <li>Add new response field WTW per TEU/km.</li>
    </ul>
    <h2>2.2.0</h2>
    <ul>
    <li>Add speed as an optional input field.</li>
    </ul>
    <h2>2.1.0</h2>
    <ul>
    <li>Add WWT and WTW Co2 emissions to vessel method response.</li>
    <li>Use the GLEC's fuel emission factor in vessel method. </li>
    </ul>
    <h2>2.0.0</h2>
    <ul>
    <li>Add usages endpoint to check the usage of the api</li>
    <li>Co2 computation for a vessel from a port to another port using GLEC Framework recommendations</li>
    </ul>
    <h2>1.1.0</h2>
    <ul>
    <li>Co2 computation for a vessel from a port to another port using GLEC Framework recommendations</li>
    </ul>
    <h2>1.0.0</h2>
    <ul>
    <li>Co2 computation for a vessel from a port to another port</li>
    </ul>
servers:
  - url: "https://api.sinay.ai/co2/api/v2/"
tags:
  - name: Co2 computation
    description: Endpoint that allows you to compute Co2 emission of a vessel for a trip from a port to another port.
paths:
  "/compute-co2":
    post:
      operationId: "computeCo2"
      summary: Retrieve co2 consumption for a trip from one port to another.
      tags:
        - Co2 computation
      description:
         <p>This endpoint is used to compute the CO2 emissions of a TEU during its journey from a port to another port.</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), but not both in the same reaquest.</p>
         <p>You can also set an optional custom average speed for the vessel during the journey, in knots. By default the average speed will be computed by our routing system.</p>
         <p>The maximum allowed speed input is 25 knots</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 the voyage length in nautical miles and an estimation of the tons of CO2 emitted for this voyage, by TEU, with different methods.</p>
         <h3>Vessel model method</h3>
         <p>In this method, 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 (hull, engine, capacity, etc.) to estimate their fuel consumption. The CO2 emission is then derived from the ship estimated fuel consumption.</p>
         <p>This method computes only Tank to Wheel co2 emission (for the moment).</p>
         <h3>Tradelane method</h3>
         <p>In this method, we use the factors given by the GLEC Framework (2019 edit). From the departure and arrival, we deduce which tradelane have been used, and we find the corresponding emission factors. Then we apply these factors to the voyage length.</p>
         <p>This method does not take into account specific vessel characteristics.</p>
         <p>This method allows to estimate Well to Tank, Tank to Wheel and Well to Wheel (ie total) co2 emissions.</p>
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/computeCo2Request"
            examples:
              co2:
                summary: "Compute Co2"
                value:
                  vessel:
                    imo: 9706906
                    speed: 13.00
                  departure:
                    portCode: "FRLEH"
                  arrival:
                    portCode: "ESBCN"
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/computeCo2Response"
        '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:
    computeCo2Request:
      type: object
      properties:
        vessel:
          type: object
          description: "vessel information for co2 request"
          "$ref": "#/components/schemas/vessel"
        departure:
          type: object
          description: "departure information for co2 request"
          "$ref": "#/components/schemas/port"
        arrival:
          type: object
          description: "arrival information for co2 request"
          "$ref": "#/components/schemas/port"
    vessel:
      type: object
      properties:
        imo:
          type: integer
          format: int64
          description: "IMO ship identification number of the vessel : 7 digits"
          example : 9706906
        mmsi:
          type: integer
          format: int64
          description: "MMSI identifier of the vessel : 9 digits"
          example : 215199000
        speed:
          type: number
          format: double
          description: "average speed in knots, should be under 25"
          example : 13.00
    port:
      type: object
      properties:
        portCode:
          type: string
          description: " UN/LOCODE (5 caracters code identifying the port according to the UNECE)"
    computeCo2Response:
      type: object
      properties:
        input:
          type: object
          "$ref": "#/components/schemas/computeCo2Request"
        length:
          type: number
          format: double
          description: "voyage length in nautical miles"
          example : 1709.7834398908199
        co2EmissionResult:
          type: object
          "$ref": "#/components/schemas/co2EmissionResults"
    co2EmissionResults:
      type: object
      description: "computed co2 emission"
      properties:
        vesselMethodResult:
          type: object
          description: "Results for the Vessel Model Method take into account the vessel characteristics and the route information between the origin and the destination."
          "$ref": "#/components/schemas/vesselMethodResult"
        tradeLaneMethodResult:
          type: object
          "$ref": "#/components/schemas/tradeLaneMethodResult"
          description: "Results for the Tradelane Method take into account origin and destination, regardless of the vessel characteristics"
    vesselMethodResult:
      type: object
      properties:
        co2Wtt:
          type: number
          format: double
          description: "co2 Well to Tank emission in Ton/TEU computed with vessel model method"
          example : 0.043543922905257035
        co2Ttw:
          type: number
          format: double
          description: "co2 Tank to Wheel emission in Ton/TEU computed with vessel model method"
          example : 0.5275513736598448
        co2Wtw:
          type: number
          format: double
          description: "co2 Well to Wheel emission in Ton/TEU computed with vessel model method"
          example : 0.5710952965651018
        WtwEmissionIntensity:
          type: number
          description: "co2 Well to Wheel emission in Ton/TEU per kilometer computed with vessel model method"
          example : 0.5710952965651018
    tradeLaneMethodResult:
      type: object
      properties:
        co2Wtt:
          type: number
          format: double
          description: "co2 Well to Tank emission in Ton/TEU computed with tradelanes method"
          example : 0.025332151445422387
        co2Ttw:
          type: number
          format: double
          description: "co2 Tank to Wheel emission in Ton/TEU computed with tradelanes method"
          example : 0.32298493092913544
        co2Wtw:
          type: number
          format: double
          description: "co2 Well to Wheel emission in Ton/TEU computed with tradelanes method"
          example : 0.3483170823745578
        WtwEmissionIntensity:
          type: number
          description: "co2 Well to Wheel emission in Ton/TEU per kilometer computed with tradelanes method"
          example :  0.00014527985
    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
    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'
    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: [ ]