openapi: "3.0.0"
info:
  title: "Metocean API"
  description: Welcome to the documentation of the Metocean 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>/metocean/api/v1</strong> for the current version.
    <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 Metocean 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>Stations weather data history retrieval</li>
    <li>Authentication using api key</li>
    </ul>
  version: "1.1.0"
servers:
  - url: "https://api.sinay.ai/metocean/api/v1"
tags:
  - name: Station
    description: Endpoints that allow you to retrieve data for a station
  - name: Model
    description: Endpoints that allow you to retrieve the list of available models
  - name: Usage
    description: Endpoints that allow you to retrieve your api usages
paths:
  "/models":
    get:
      operationId: "retrieveModels"
      summary: "Retrieve available models"
      description:
        <p>The endpoint allows you to retrieve available models</p>
      tags:
        - Model
      responses:
        '200':
          description: "The list of models"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models'
        '401':
          $ref: '#/components/responses/unauthorized'
        '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'
  "/stations":
    parameters:
      - $ref: '#/components/parameters/dryRun'
    post:
      operationId: "retrieveStations"
      summary: "Retrieve station"
      description:
        <p>The endpoint allows you to retrieve historical weather data</p>
        <h1>Request</h1>
        <p>To retrieve data, you must define the position of the stations, the time interval and the model type</p>
        <h2>Stations position</h2>
        <p>There are three ways to define an area</p>
        <ul>
        <li>Around a position, from a center (longitude, latitude) and a radius, we will find and return data for stations which are in a circle around the coordinates (radius in km)</li>
        <li>From a station name, we will return data for this station name, and an error if the station name does not exist</li>
        <li>From a GeoJSON, we will find and return all stations found in the GeoJSON area, Only Geometry objects are allowed (not Feature and FeatureCollection)</li>
        </ul>
        <h2>Time interval</h2>
        <p>You must define the time interval for which you want to retrieve data. As our data are separated in calendar month, you can only define the year and the month for start and end time. The accepted format is yyyy-mm, for example 2022-01.</p>
        <p></p>
        <h2>Model type</h2>
        <p>You must select the model type. You can retrieve them using the retrieve models endpoint.</p>
        <h2>Dry run</h2>
        <p>To avoid to be charged for something you don't want, you can test the request without any charge, you will be able to see the cost of your request and the results, but you won't have access to the links to download the data. A query parameter is present to activate the dry run.</p>
        <h1>Response</h1>
        <h2>Data</h2>
        <p>You will find a list of stations we found for your request.</p>
        <p>For each station, you will find the list of retrieved data with associated metadata.</p>
        <h2>Api units</h2>
        <p>An header named <strong>x-api-units</strong> will be added in each answer to tell you how many units the request cost you. If the request is done in dry run, you won't be charge, but you will be able to see how many it would cost you</p>
      tags:
        - Station
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/stationsRequest'
            examples:
              geojsonArea:
                summary: "Request with GeoJSON"
                description: "All stations found in the GeoJSON area will be returned"
                value:
                  area:
                    geoJson:
                      type: "Polygon"
                      coordinates:
                        -
                          -
                            - 35.5078125
                            - -55.77657301866769
                          -
                            - 36.2109375
                            - -65.5129625532949
                          -
                            - 65.0390625
                            - -64.92354174306496
                          -
                            - 64.6875
                            - -55.17886766328199
                          -
                            - 52.03125
                            - -50.95842672335992
                          -
                            - 35.5078125
                            - -55.77657301866769
                  time:
                    start: "2021-06"
                    end: "2021-08"
                  model: "Global"
              stationNameArea:
                summary: "Request with a station name"
                description: "Return the station with the given station name"
                value:
                  area:
                    stationName: "W05250N400"
                  time:
                    start: "2021-06"
                    end: "2021-08"
                  model: "Global"
              circleArea:
                summary: "Request with position and a radius"
                description: "Return the nearest station around the coordinates"
                value:
                  area:
                    circle:
                      center:
                        - -52.502121
                        - 39.999298
                      radius: 10
                  time:
                    start: "2021-06"
                    end: "2021-08"
                  model: "Global"
      responses:
        '200':
          description: "The list of stations"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stationsResponse'
          headers:
            x-api-units:
              schema:
                type: integer
              description: The cost of the request in API units.
        '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'
components:
  schemas:
    models:
      type: array
      items:
        $ref: '#/components/schemas/model'
    model:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/modelName'
    modelName:
      type: string
    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
    stationsRequest:
      type: object
      required:
        - area
        - time
        - model
      properties:
        area:
          $ref: '#/components/schemas/stationsArea'
        time:
          $ref: '#/components/schemas/stationsTime'
        model:
          $ref: '#/components/schemas/stationsModel'
    stationsArea:
      type: object
      properties:
        circle:
          $ref: '#/components/schemas/circle'
        stationName:
          $ref: '#/components/schemas/stationName'
        geoJson:
          $ref: '#/components/schemas/geoJson'
    circle:
      type: object
      required:
        - radius
        - center
      properties:
        radius:
          $ref: '#/components/schemas/radius'
        center:
          $ref: '#/components/schemas/coordinates'
    coordinates:
      type: array
      items:
        type: number
        format: double
    radius:
      type: number
      format: double
    stationName:
      type: string
    geoJson:
      type: object
    stationsTime:
      type: object
      properties:
        start:
          $ref: '#/components/schemas/yearMonthDate'
        end:
          $ref: '#/components/schemas/yearMonthDate'
    stationsModel:
      type: string
    yearMonthDate:
      type: string
    stationsResponse:
      type: object
      properties:
        stations:
          $ref: '#/components/schemas/stations'
    stations:
      type: array
      items:
        $ref: '#/components/schemas/station'
    station:
      type: object
      required:
        - longitude
        - latitude
        - stationName
      properties:
        stationName:
          $ref: '#/components/schemas/stationName'
        longitude:
          $ref: '#/components/schemas/longitude'
        latitude:
          $ref: '#/components/schemas/latitude'
        referencesMatrixFile:
          $ref: '#/components/schemas/referencesMatrixFile'
        data:
          $ref: '#/components/schemas/dataArray'
      example:
        stationName: "E06500S645"
        referencesMatrixFile: "https://2222222-2222222-2222222-2222222.com"
        longitude: 25.0
        latitude: 10.5
        data:
          - time: "2020-01"
            gridName: "Global 30min"
            modelVersion: "v6.07"
            companyName: "Aktis Hydraulics"
            link: "https://1111111-1111111-1111111-1111111.com"
            linkExpirationTime: "2022-01-01T10:00:00.000Z"
          - time: "2020-02"
            gridName: "Global 30min"
            modelVersion: "v6.07"
            companyName: "Aktis Hydraulics"
            link: "https://2222222-2222222-2222222-2222222.com"
            linkExpirationTime: "2022-01-01T10:00:00.000Z"
    referencesMatrixFile:
      type: string
    longitude:
      type: number
      format: double
    latitude:
      type: number
      format: double
    dataArray:
      type: array
      items:
        $ref: '#/components/schemas/data'
    data:
      type: object
      required:
        - time
        - modelVersion
        - gridName
        - companyName
      properties:
        time:
          $ref: '#/components/schemas/yearMonthDate'
        link:
          $ref: '#/components/schemas/link'
        linkExpirationTime:
          $ref: '#/components/schemas/linkExpirationTime'
        modelVersion:
          $ref: '#/components/schemas/modelVersion'
        gridName:
          $ref: '#/components/schemas/gridName'
        companyName:
          $ref: '#/components/schemas/companyName'
    link:
      type: string
    linkExpirationTime:
      type: string
      format: date-time
    modelVersion:
      type: string
    gridName:
      type: string
    companyName:
      type: string
    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:
    dryRun:
      in: query
      name: dryRun
      required: false
      schema:
        type: boolean
        default: false
      description: Useful to test the request before doing it really. If dryrun is activated, files won't be present in the answer, and the call won't be charged
    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: [ ]