swagger: '2.0'
info:
  title: Harvesting window API staging
  description: Harvesting window API
  version: 1.0.0
host: api.harvesting-window.staging.cropio.com

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: apiKey
    name: key
    in: query

security:
  - api_key: [ ]

definitions:
  FieldGeometry:
    type: object
    description: GeoJSon geometry of a single field. Polygon and MultiPolygon are supported
    discriminator: type
    required:
      - type
    properties:
      type:
        type: string
        enum:
          - Polygon
          - MultiPolygon
        description: the geometry type

  Point3D:
    type: array
    description: Point in 3D space
    minItems: 2
    maxItems: 3
    items:
      type: number

  Polygon:
    type: object
    description: GeoJSon geometry
    allOf:
      - $ref: "#/definitions/FieldGeometry"
      - properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                $ref: '#/definitions/Point3D'

  MultiPolygon:
    type: object
    description: GeoJSon geometry
    allOf:
      - $ref: "#/definitions/FieldGeometry"
      - properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                type: array
                items:
                  $ref: '#/definitions/Point3D'

  SowingDate:
    type: string
    description: Sowing date in ISO format (%Y-%m-%d)

  Date:
    type: string
    description: Prediction date in ISO format (%Y-%m-%d)

  Crop:
    type: string
    description: Field crop name

  HistoricalDataElement:
    type: array
    description: Date in ISO format (%Y-%m-%d) and Value
    items: {}
    example:
      - "%date (in %Y-%m-%d format)"
      - number

  FullSoilMoistureDataElement:
    type: array
    description: Date in ISO format (%Y-%m-%d) and Value
    items: { }
    example:
      - "%date (in %Y-%m-%d format)"
      - [number, number, number, number]

  FullWeatherDataElement:
    type: object
    description: Date as key and snow, wind_speed, precipitation, temperature_max, temperature_min, temperature_mean as value
    items: {}
    example: {"%date (in %Y-%m-%d format)": {
                        "snow": 0.16,
                        "wind_speed": 3.04,
                        "precipitation": 0.0,
                        "temperature_max": 2.74,
                        "temperature_min": -1.95,
                        "temperature_mean": 0.89
                    }}

  WeatherDataElement:
    type: object
    description: Date as key and {'growth_degree_days:' number, 'accumulated_precipitation:' number} as value
    items: { }
    example: { "%date (in %Y-%m-%d format)": { growth_degree_days: value, accumulated_precipitation: value } }

  NdviValues:
    type: array
    description: Historical data for model (ndvi_values). Could be empty array.
    items:
      $ref: '#/definitions/HistoricalDataElement'

  SoilMoisture:
    type: array
    description: Historical data for model (soil_moisture_values). Could be empty array.
    items:
      $ref: '#/definitions/HistoricalDataElement'

  FullSoilMoisture:
    type: array
    description: Historical data for model (soil_moisture_values). Could be empty array.
    items:
      $ref: '#/definitions/FullSoilMoistureDataElement'

  WeatherData:
    type: array
    description: Weather data
    items:
      $ref: '#/definitions/WeatherDataElement'

  FullWeatherData:
    type: array
    description: Full weather data (with snow, wind speed, precipitation and temperature)
    items:
      $ref: '#/definitions/FullWeatherDataElement'

  StagesUpdate:
    type: object
    description: Data to apply client stage corrections
    items: {}
    example: {"%stage_name": "date in %Y-%m-%d format"}

  Scale:
    type: string
    description: Scale for growth stages V2

  HarwestingWindowRequestItem:
    type: object
    properties:
      shape:
        $ref: '#/definitions/FieldGeometry'
      sowing_date:
        $ref: '#/definitions/SowingDate'
      ndvi_values:
        $ref: '#/definitions/NdviValues'
      soil_moisture:
        $ref: '#/definitions/SoilMoisture'
      weather_data:
        $ref: '#/definitions/WeatherData'
      date:
        $ref: '#/definitions/Date'
      crop:
        $ref: '#/definitions/Crop'
    required:
      - shape
      - sowing_date
      - crop
      - ndvi_values
      - soil_moisture
      - weather_data

  HarwestingWindowBatchRequest:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/HarwestingWindowRequestItem'

  GrainMoistureRequestItem:
    type: object
    properties:
      year:
        type: integer
      shape:
        $ref: '#/definitions/FieldGeometry'
      sowing_date:
        $ref: '#/definitions/SowingDate'
      harvesting_date:
        $ref: '#/definitions/Date'
      variety:
        type: string
        description: "something of the following: [SY_CHORINTOS,SY_PREMEO,SY_FENOMEN,SY_FORTAGO,SY_SCORPIUS,SY_TELIAS,SY_TALISMAN,SY_ENERMAX,SY_IMPULSE,SY_ROTANGO,SY_IGNIS,SY_ANDROMEDA,SY_MARIMBA,SY_OZONE,NK_FALKONE,SY_AMBADOR,SY_KARDONA,EVORA,SY_INVICTUS,SY_ABELARDO,SY_HIKARI,SY_UNITOP]"
      ndvi_values:
        $ref: '#/definitions/NdviValues'
      soil_moisture:
        $ref: '#/definitions/SoilMoisture'
    required:
      - year
      - shape
      - sowing_date
      - harvesting_date

  GrainMoistureBatchRequest:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/GrainMoistureRequestItem'

  GrowthStagesRequestItem:
    type: object
    properties:
      shape:
        $ref: '#/definitions/FieldGeometry'
      sowing_date:
        $ref: '#/definitions/SowingDate'
      crop:
        $ref: '#/definitions/Crop'
      ndvi_values:
        $ref: '#/definitions/NdviValues'
      soil_moisture:
        $ref: '#/definitions/SoilMoisture'
      weather_data:
        $ref: '#/definitions/WeatherData'
      stages_update:
        $ref: '#/definitions/StagesUpdate'
    required:
      - shape
      - sowing_date
      - crop
      - ndvi_values
      - soil_moisture
      - weather_data

  GrowthStagesRequestItemV2:
    type: object
    properties:
      shape:
        $ref: '#/definitions/FieldGeometry'
      sowing_date:
        $ref: '#/definitions/SowingDate'
      crop:
        $ref: '#/definitions/Crop'
      ndvi_values:
        $ref: '#/definitions/NdviValues'
      soil_moisture:
        $ref: '#/definitions/FullSoilMoisture'
      weather_data:
        $ref: '#/definitions/FullWeatherData'
      stages_update:
        $ref: '#/definitions/StagesUpdate'
      scale:
        $ref: '#/definitions/Scale'
    required:
      - shape
      - sowing_date
      - crop
      - ndvi_values
      - soil_moisture
      - weather_data

  ProductivityEstimationRequestItemV2:
    type: object
    properties:
      shape:
        $ref: '#/definitions/FieldGeometry'
      sowing_date:
        $ref: '#/definitions/SowingDate'
      crop:
        $ref: '#/definitions/Crop'
      ndvi_values:
        $ref: '#/definitions/NdviValues'
      soil_moisture:
        $ref: '#/definitions/FullSoilMoisture'
      weather_data:
        $ref: '#/definitions/FullWeatherData'
    required:
      - shape
      - sowing_date
      - crop
      - ndvi_values
      - soil_moisture
      - weather_data

  GrowthStagesBatchRequest:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/GrowthStagesRequestItem'

  GrowthStagesBatchRequestV2:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/GrowthStagesRequestItemV2'

  ProductivityEstimationBatchRequestV2:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/ProductivityEstimationRequestItemV2'

  ModelsInfoResponseItem:
    type: object
    properties:
      crop_name:
        $ref: '#/definitions/ItemMeta'

  SingeResponseItem:
    type: object
    properties:
      error:
        $ref: '#/definitions/ItemError'
      prediction:
        $ref: '#/definitions/ItemPrediction'
      meta:
        $ref: '#/definitions/ItemMeta'

  GrowthStagesBatchResponseItem:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/GrowthStagesResponseItem'

      metas:
        type: array
        items:
          $ref: '#/definitions/MetasItem'

  GrowthStagesBatchResponseItemV2:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/GrowthStagesResponseItemV2'

  ProductivityEstimationBatchResponseItemV2:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/ProductivityEstimationResponseItemV2'

  GrainMoistureBatchResponseItem:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/GrainMoistureResponseItem'

      metas:
        type: array
        items:
          $ref: '#/definitions/MetasItem'


  BatchResponseItem:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/ResponseItem'

      metas:
        type: array
        items:
          $ref: '#/definitions/MetasItem'


  ResponseItem:
    type: object
    properties:
      error:
        $ref: '#/definitions/ItemError'
      prediction:
        $ref: '#/definitions/ItemPrediction'
      meta_ref:
        type: string
        description: Model uuid

  GrowthStagesResponseItem:
    type: object
    properties:
      error:
        $ref: '#/definitions/ItemError'
      prediction:
        $ref: '#/definitions/GrowthStagesItemPrediction'
      meta_ref:
        type: string
        description: Model uuid

  GrainMoistureResponseItem:
    type: object
    properties:
      error:
        $ref: '#/definitions/ItemError'
      prediction:
        $ref: '#/definitions/GrainMoistureItemPrediction'
      meta_ref:
        type: string
        description: Model uuid
    example: {"error":"","prediction":{"grain_moisture":22.126509190987818},"meta":{"name":"grain_moisture","uuid":"ede33314-c9ad-47ce-92f5-93d34c89be91","version":"v.1.0.0"}}

  GrowthStagesResponseItemV2:
    type: object
    properties:
      error:
        $ref: '#/definitions/ItemError'
      prediction:
        $ref: '#/definitions/GrowthStagesItemPredictionV2'
      meta_ref:
        type: string
        description: Model uuid

  ProductivityEstimationResponseItemV2:
    type: object
    properties:
      error:
        $ref: '#/definitions/ItemError'
      prediction:
        $ref: '#/definitions/ProductivityEstimationItemPredictionV2'
      meta_ref:
        type: string
        description: Model uuid

  ItemError:
    type: string
    description: Describe error in case if item cant be processed

  ItemPrediction:
    type: object
    properties:
      ytd:
        type: number
        description: Year to date for prediction

  GrowthStagesItemPrediction:
    type: object
    properties:
      stages_ytd:
        type: object
        description: Stages name and day of year where stage was firstly appeared
        example: {00_sd: 100, 01_01: 105}
      stages_date:
        type: object
        description: Stages name and date where stage was firstly appeared
        example: {00_sd: "2020-04-09", 01_01: "2020-04-14"}

  GrainMoistureItemPrediction:
    type: object
    properties:
      grain_moisture:
        type: number
        description: Grain moisture prediction for specified harvesting_date in terms of given crop information
        example: 22.126509190987818

  GrowthStagesItemPredictionV2:
    type: object
    properties:
      stages_date:
        type: object
        description: Stages name and date where stage was firstly appeared
        example: { "05_stage": "2021-09-04", "07_stage": "2021-09-16" }

  ProductivityEstimationItemPredictionV2:
    type: number
    description: Estimated productivity of given field
    example: 204.32

  ItemMeta:
    type: object
    properties:
      name:
        type: string
        description: Model name
      uuid:
        type: string
        description: Model uuid
      version:
        type: string
        description: Model version
      scale:
        type: array
        description: Supported scale
        items:
          type: string
      scale_name:
        type: string
        description: Scale internal name
      model_val_info:
        type: object
        description: Model validation information

  MetasItem:
    type: object
    properties:
      meta_ref:
        $ref: '#/definitions/ItemMeta'


parameters:
  field_harvest_window_request:
    in: body
    name: body
    description: Single field to predict harvest window
    schema:
      $ref: '#/definitions/HarwestingWindowRequestItem'

  fields_batch_harvest_window_request:
    in: body
    name: body
    description: Fields batch to predict harvest window
    schema:
      $ref: '#/definitions/HarwestingWindowBatchRequest'

  field_growth_stages_request:
    in: body
    name: body
    description: Single field to predict harvest window
    schema:
      $ref: '#/definitions/GrowthStagesRequestItem'

  fields_batch_growth_stages_request:
    in: body
    name: body
    description: Fields batch to predict harvest window
    schema:
      $ref: '#/definitions/GrowthStagesBatchRequest'

  field_grain_moisture_request:
    in: body
    name: body
    description: Single field to predict harvest window
    schema:
      $ref: '#/definitions/GrainMoistureRequestItem'

  fields_batch_grain_moisture_request:
    in: body
    name: body
    description: Fields batch to predict harvest window
    schema:
      $ref: '#/definitions/GrainMoistureBatchRequest'

  field_growth_stages_request_v2:
    in: body
    name: body
    description: Single field to predict harvest window
    schema:
      $ref: '#/definitions/GrowthStagesRequestItemV2'

  fields_batch_growth_stages_request_v2:
    in: body
    name: body
    description: Fields batch to predict harvest window
    schema:
      $ref: '#/definitions/GrowthStagesBatchRequestV2'

  field_productivity_estimation_request_v2:
    in: body
    name: body
    description: Single field to predict productivity
    schema:
      $ref: '#/definitions/ProductivityEstimationRequestItemV2'

  fields_batch_productivity_estimation_request_v2:
    in: body
    name: body
    description: Fields batch to predict productivity
    schema:
      $ref: '#/definitions/ProductivityEstimationBatchRequestV2'

schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: https://harvesting-window-staging-5do5evgt4a-ew.a.run.app
  protocol: h2
  deadline: 300 # this is the CloudRun default value

paths:
  /api/v1/harvesting_window/predict:
    post:
      consumes:
        - application/json
      description: Returns prediction for a single field
      operationId: apiV1HarvestWindowPredict
      parameters:
        - $ref: '#/parameters/field_harvest_window_request'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/SingeResponseItem'
        '422':
          description: Unprocessable Entity. Error field in the Item will be not null
          schema:
            $ref: '#/definitions/SingeResponseItem'


  /api/v1/harvesting_window/predict/batch:
    post:
      consumes:
        - application/json
      description: Returns prediction for fields batch
      operationId: apiV1HarvestWindowBatchPredict
      parameters:
        - $ref: '#/parameters/fields_batch_harvest_window_request'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/BatchResponseItem'


  /api/v1/growth_stages/predict:
    post:
      consumes:
        - application/json
      description: Returns prediction for a single field
      operationId: apiV1GrowthStagesPredict
      parameters:
        - $ref: '#/parameters/field_growth_stages_request'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/GrowthStagesResponseItem'
        '422':
          description: Unprocessable Entity. Error field in the Item will be not null
          schema:
            $ref: '#/definitions/SingeResponseItem'


  /api/v1/growth_stages/predict/batch:
    post:
      consumes:
        - application/json
      description: Returns prediction for fields batch
      operationId: apiV1GrowthStagesBatchPredict
      parameters:
        - $ref: '#/parameters/fields_batch_growth_stages_request'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/GrowthStagesBatchResponseItem'

  /api/v1/grain_moisture/predict:
    post:
      consumes:
        - application/json
      description: Returns prediction of grain moisture for specified harvest_date with given field information
      operationId: apiV1GrainMoisturePredict
      parameters:
        - $ref: '#/parameters/field_grain_moisture_request'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/GrainMoistureResponseItem'
        '422':
          description: Unprocessable Entity. Error field in the Item will be not null
          schema:
            $ref: '#/definitions/SingeResponseItem'


  /api/v1/grain_moisture/predict/batch:
    post:
      consumes:
        - application/json
      description: Returns prediction of grain moisture for specified harvest_date's with given field's information
      operationId: apiV1GrainMoistureBatchPredict
      parameters:
        - $ref: '#/parameters/fields_batch_grain_moisture_request'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/GrainMoistureBatchResponseItem'

  /api/v1/growth_stages/models:
    get:
      description: Returns information about V1 models
      operationId: apiV1GetModelsInfo
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ModelsInfoResponseItem'

  /api/v2/growth_stages/predict:
    post:
      consumes:
        - application/json
      description: Returns prediction for a single field
      operationId: apiV2GrowthStagesPredict
      parameters:
        - $ref: '#/parameters/field_growth_stages_request_v2'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/GrowthStagesResponseItemV2'
        '422':
          description: Unprocessable Entity. Error field in the Item will be not null
          schema:
            $ref: '#/definitions/SingeResponseItem'


  /api/v2/growth_stages/predict/batch:
    post:
      consumes:
        - application/json
      description: Returns prediction for fields batch
      operationId: apiV2GrowthStagesBatchPredict
      parameters:
        - $ref: '#/parameters/fields_batch_growth_stages_request_v2'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/GrowthStagesBatchResponseItemV2'

  /api/v2/productivity_estimation/predict:
    post:
      consumes:
        - application/json
      description: Returns prediction for a single field
      operationId: apiV2ProductivityEstimationPredict
      parameters:
        - $ref: '#/parameters/field_productivity_estimation_request_v2'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ProductivityEstimationResponseItemV2'
        '422':
          description: Unprocessable Entity. Error field in the Item will be not null
          schema:
            $ref: '#/definitions/SingeResponseItem'

  /api/v2/productivity_estimation/predict/batch:
    post:
      consumes:
        - application/json
      description: Returns prediction for fields batch
      operationId: apiV2ProductivityEstimationBatchPredict
      parameters:
        - $ref: '#/parameters/fields_batch_productivity_estimation_request_v2'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ProductivityEstimationBatchResponseItemV2'

  /api/v2/growth_stages/models:
    get:
      description: Returns information about V2 models
      operationId: apiV2GetModelsInfo
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ModelsInfoResponseItem'