MRV Products

MRV Products#

MRV API is able to perform a variety of analyses. Here we give a list of the currently available capabilities / products in MRV API. Please contact Agreena Sales if you are missing some capability in this list.

Note

Each MRV product is independent and your client must be registered to use it before you start making requests for the product. Please check Client-Product Authorisation section to learn how you can activate different MRV capabilities into your client. Otherwise, if for example you trigger a request for a tillage verification and you have not activated that product, the API will return an error message:

{
  "app_exception": "AuthorizationError",
  "context": {
    "message": "Client is not authorized to perform tillage."
  }
}

All the result examples in this section are presented as they are returned by the Requests API endpoint /v1/requests/<request_id>/results. The response payload in that endpoint will always have this common schema:

  • id: The UUID of the Request that the Results belong to.

  • status: The current status of the Request. One of Pending, Completed or Failed.

  • start_date: Starting date of the Request.

  • end_date: End date of the Request.

  • fields: An array of objects containing individual information of Fields affected by the Request, with the different capability Results.

    • field_id: UUID of the Field.

    • tillage: results of tillage analysis.

    • deforestation: results of deforestation analysis.

    • cover_crop: results of cover crop analysis.

    • crop_type: results of crop type analysis.

    • soil_moisture: results of soil moisture analysis.

    • field_detection: results of field boundary detection, GeoJSON representation of the calculated geographical boundary.

Field Boundary Detection#

Capability: boundary-detection

Unlike the rest of MRV products, this one is not triggered by sending a new request, but by creating new fields using one of the detection endpoints.

The results of a field boundary detection operation will be shown under the field_detection key.

Results example#

{
  "id": "0e220c79-61b9-4d86-b2ac-2e16e538382b",
  "status": "Completed",
  "start_date": "2023-10-05",
  "end_date": "2023-10-05",
  "fields": [
    {
      "field_id": "292218e4-a9c1-44cc-a527-6ad8141f5170",
      "tillage": null,
      "deforestation": null,
      "cover_crop": null,
      "crop_type": null,
      "soil_moisture": null,
      "field_detection": {
        "boundary": {
          "coordinates": [
            [
              [
                10.28795574637229,
                56.272752497952524
              ],
              [
                10.287563610014672,
                56.271241967681306
              ],
              [
                10.289303715101397,
                56.2706840089823
              ],
              [
                10.289916428159529,
                56.27242590186694
              ],
              [
                10.28795574637229,
                56.272752497952524
              ]
            ]
          ],
          "type": "Polygon"
        },
        "area": 18.987264263434742,
        "point": {
          "type": "Point",
          "coordinates": [
            10.28881220272197,
            56.27190730669585
          ]
        },
        "land_use": "Crops",
        "country_code": "DNK",
        "climate_zone": "cool_temperate_moist"
      },
      "soil_type": null,
      "ndvi": null
    }
  ]
}

Cover crops#

Capability: cover-crops

Performs Cover Crops detection over the given fields for a given time range.

The results of the operation will be shown in the cover_crop section. It will consist of a key has_cover_crop which can have the value true or false depending on if cover crops technique has been applied to the specific field or not.

Results example#

{
  "id": "414b53ec-597a-4638-99c7-ccb2a2426720",
  "status": "Completed",
  "start_date": "2022-05-01",
  "end_date": "2022-08-31",
  "fields": [
    {
      "field_id": "1d4b272d-a744-43e6-88e6-babcf4c37bf6",
      "tillage": null,
      "deforestation": null,
      "cover_crop": {
        "cover_crops_results": {
          "has_cover_crop": true
        }
      },
      "crop_type": null,
      "soil_moisture": null,
      "field_detection": null,
      "soil_type": null,
      "ndvi": null
    }
  ]
}

Tillage#

Capability: tillage

Runs an automated tillage verification over the given fields during the specified time range.

The results of the analysis will be shown in the tillage section. They will consist of a simple map with a single type field and the value for the tillage verification, which can be one of:

  • conventional: conventional tillage (< 15% crop residue cover).

  • reduced: minimum tillage (15-30% crop residue cover).

  • no_till: no tillage (> 30% crop residue cover).

Results example#

{
  "id": "6454a659-48b6-4539-833b-a381bf364991",
  "status": "Completed",
  "start_date": "2022-05-01",
  "end_date": "2022-08-31",
  "fields": [
    {
      "field_id": "1d4b272d-a744-43e6-88e6-babcf4c37bf6",
      "tillage": {"type": "conventional"},
      "deforestation": null,
      "cover_crop": null,
      "crop_type": null,
      "soil_moisture": null,
      "field_detection": null,
      "soil_type": null,
      "ndvi": null
    }
  ]
}

Crop Type Classification#

Capability: crop-type

Performs a crop type detection analysis over the given fields for the specified dates range.

The results of the crop type verification will be shown under the crop_type section, consisting of a simple map with a single name key, where the value will be the name of the crop.

Results example#

{
  "id": "54ccfd97-ddc6-4206-b8e7-f5551bf2ccf4",
  "status": "Completed",
  "start_date": "2022-01-01",
  "end_date": "2022-03-01",
  "fields": [
    {
      "field_id": "84ccfd97-ddc6-4206-b8e7-f5551bf2ccf4",
      "tillage": null,
      "deforestation": null,
      "cover_crop": null,
      "crop_type": {"name": "corn"},
      "field_detection": null,
      "ndvi": null
    }
  ]
}

NDVI#

Capability: ndvi

Runs an NDVI analysis over the given fields for the given time ranges.

The results of the NDVI analysis will be shown under the ndvi section. They will consist of a monthly average calculation of the NDVI index for the requested months. E.g. if the user requests an NDVI analysis for the time range starting on May 2022 and ending at 31st August 2022, the results will contain the 4 months of May, June, July and August.

Results example#

{
  "id": "c555dc13-04c9-4079-9c0a-ab0cc33eeb97",
  "status": "Completed",
  "start_date": "2022-05-01",
  "end_date": "2022-08-31",
  "fields": [
    {
      "field_id": "97dbcd97-b901-4f9b-b191-b818fc747d37",
      "tillage": null,
      "deforestation": null,
      "cover_crop": null,
      "crop_type": null,
      "soil_moisture": null,
      "field_detection": null,
      "soil_type": null,
      "ndvi": {
        "monthly_average": {
          "2022-05": null,
          "2022-06": null,
          "2022-07": null,
          "2022-08": 0.37751325477152764
        }
      }
    }
  ]
}

NDVI Imagery#

Capability: ndvi-imagery

Performs an NDVI analysis and generates resulting images that graphically shows the NDVI values over the selected area.

The GeoTIFF images and the derived JPEG images with the data graphs will all be stored in a GCS bucket from where it can be downloaded. The response will show Google Bucket gs:// URLs that can be used to access the images only by authorised Agreena staff, and also regular https:// signed URLs that can be used by anyone with the link to temporarily access the data.

Warning

The signed URL links will only be valid for 7 days starting on the image_date time.

Results example#

{
  "id": "27eab3df-86f8-4900-80cd-9178e8b2ae26",
  "status": "Completed",
  "start_date": "2021-01-01",
  "end_date": "2021-04-30",
  "fields": [
    {
      "field_id": "9d6765d0-c489-4d1a-8614-955abbe810ea",
      "tillage": null,
      "deforestation": null,
      "cover_crop": null,
      "crop_type": null,
      "soil_moisture": null,
      "field_detection": null,
      "soil_type": null,
      "ndvi": null,
      "ndvi_imagery": {
        "urls": {
          "jpg_url": "gs://agreena-ndvi-imagery-staging/S2B_MSIL2A_20210109T112339_N0500_R037_T30UXC_20230610T130253_9d6765d0-c489-4d1a-8614-955abbe810ea.jpg",
          "raster_url": "gs://agreena-ndvi-imagery-staging/S2B_MSIL2A_20210109T112339_N0500_R037_T30UXC_20230610T130253_9d6765d0-c489-4d1a-8614-955abbe810ea.tif",
          "jpg_signed_url": "https://storage.googleapis.com/agreena-ndvi-imagery-staging/S2B_MSIL2A_20210109T112339_N0500_R037_T30UXC_20230610T130253_9d6765d0-c489-4d1a-8614-955abbe810ea.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=mrv-airflow2-gsa%40hbt-staging.iam.gserviceaccount.com%2F20240620%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20240620T114302Z&X-Goog-Expires=604800&X-Goog-SignedHeaders=host&X-Goog-Signature=70b7f6dc07030ead6f918a27c9fc04d6f550337704a5de1e04e19ff38b1c76f1b06f24ab110cccc7bae0aeaaaf78e08df0ef92a146748cd9251feabab15a0f5c7a4b0226ee387bc03a2d19675316aef542786bdf69642eea8df28fa31c9185f0e0db0c30304dacb269c360decc4c5091dfb56568d26aed0896b1b7250ec39f4a10ec293db4c28b78f722e440e5f3321512cb8eb01087db7a8e1da86f964acb5afe1386145adc1c17ff1baae844f2b3acd02e48115ce700a20d975a754c04cd1920ded1a0cfe50fd3212b9685718d8f0dde13a5dac314129fbd18583a53ba909624745511d029dc3b6ddc703ceeb99f1f28e8e00e796ea9c989323db6e353fcf2",
          "raster_signed_url": "https://storage.googleapis.com/agreena-ndvi-imagery-staging/S2B_MSIL2A_20210109T112339_N0500_R037_T30UXC_20230610T130253_9d6765d0-c489-4d1a-8614-955abbe810ea.tif?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=mrv-airflow2-gsa%40hbt-staging.iam.gserviceaccount.com%2F20240620%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20240620T114302Z&X-Goog-Expires=604800&X-Goog-SignedHeaders=host&X-Goog-Signature=29c2a37bd9920c60ef2136c39b9b1fa0d3bdb759ccf51bcdac2d448be63ee716568f9d473de35b667593aa88f8b0e5a5c11207b6a9ee3410f647580dcaca99f0c8c0495d76986ca8351aec8e92cb1bf1ac84660b3941e3e19209a5349ad277a3b3d82c4c14a259286186c62aad0b068e405057f6568895d30cd311a1e40cb9df8cbbd9664bbb11197fe89f83cde320f160b6cd50461df4f159b2628fdc0ab4cbf91716898aecb327d259307a12957038c1e9a85d66c2264fa64183ab67d46c8a3d3e78542213b4eff918bfccbeaff8abc9ef5b9a352de68a158a1c139e745a35117138f746fd688c255d9546347e2c11f4bb52adc6951aeeaa35dbc01c546536"
        },
        "image_date": "2021-01-09T11:26:44.040000Z"
      }
    }
  ]
}

Deforestation#

Capability: deforestation

Performs a deforestation analysis over the given fields for the specified dates range.

The results of this analysis will be shown under the deforestation section. They will include a detailed insight of data per year, as well as some aggregated data.

Results example#

{
  "id": "421a5e69-4dce-49f3-b3ae-0dacc5643041",
  "status": "Completed",
  "start_date": "2001-05-01",
  "end_date": "2022-10-01",
  "fields": [
    {
      "field_id": "f9212642-f8ad-4593-9dbb-28782d5f82c0",
      "tillage": null,
      "deforestation": {
        "overview": {
          "clusters": 12,
          "percent_deforested": 93.44262295081968,
          "hectares": 3.111639344262295
        },
        "above_thresholds": {
          "clusters": 2,
          "percent_deforested": 44.26229508196721,
          "hectares": 1.4739344262295082
        },
        "years": {
          "2001": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2002": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2003": {
            "cluster_size_ha": [
              0.05459016393442623,
              0.05459016393442623
            ],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0.10918032786885246,
            "percent_deforested": 3.278688524590164
          },
          "2004": {
            "cluster_size_ha": [
              0.2183606557377049,
              0.8734426229508196,
              0.6004918032786886,
              0.10918032786885246
            ],
            "percentage_deforested_threshold": 44.26229508196721,
            "size_ha_threshold": 1.4739344262295082,
            "total_cluster_size_ha": 1.8014754098360655,
            "percent_deforested": 54.09836065573771
          },
          "2005": {
            "cluster_size_ha": [
              0.05459016393442623,
              0.32754098360655737,
              0.10918032786885246,
              0.16377049180327868
            ],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0.6550819672131147,
            "percent_deforested": 19.672131147540984
          },
          "2006": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2007": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2008": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2009": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2010": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2011": {
            "cluster_size_ha": [
              0.16377049180327868,
              0.3821311475409836
            ],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0.5459016393442623,
            "percent_deforested": 16.39344262295082
          },
          "2012": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2013": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2014": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2015": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2016": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2017": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2018": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2019": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2020": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2021": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          },
          "2022": {
            "cluster_size_ha": [],
            "percentage_deforested_threshold": 0,
            "size_ha_threshold": 0,
            "total_cluster_size_ha": 0,
            "percent_deforested": 0
          }
        }
      }
    }
  ]
}

Where:

  • above_thresholds: data above the threshold.

    • clusters: total number of clusters above the threshold.

    • percent_deforested: total percent deforested above the threshold.

    • hectares: total hectares above the threshold.

  • overview: general data overview, including everything above and below the threshold.

    • clusters: total number of clusters.

    • percent_deforested: total percent deforested.

    • hectares: total hectares deforested.

  • years: detail of every year of the requested time range. A map in which keys are the year number and the values are a map with data for the year:

    • cluster_size_ha: an array of floats, each representing a cluster’s size. The total number of clusters can be inferred from the array size.

    • percentage_deforested_threshold: the deforested percentage of all the clusters above the threshold.

    • size_ha_threshold: the size in hectares of all the clusters above the threshold.

    • percentage_deforested: the total deforested percentage of all the clusters.

    • total_cluster_size_ha: the total size of the clusters, in hectares.

Contents