Marker Service API

API Overview

The Marker service API is a RESTful API interface to various markers. You can browse the reference docs here.

This chapter describes the structure of the markers data provided by the Markers service API.

Bare-soil marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`observationCount`	Count of all FOI's bare-soil observations
`markerObservations`	List of bare-soil observations
`date`	Signal acquisition date
`confidence`	Confidence in the observation being bare-soil (value between 0 and 1)

Example response

{
  "id": "CY22.MARKER.588-10837450",
  "markerTypeId": "CY22.CL_MT.S2L2A_BARE_SOIL",
  "impl" : "OBSERVATION",
  "inferenceId": "CY22.INFERENCE.588",
  "foiId": "CY22.FOI.10837450",
  "status": "OK",
  "observationCount": 37,
  "markerObservations": [
    {
      "date": "2021-10-08",
      "confidence": 0.9277381
    },
    {
      "date": "2021-10-10",
      "confidence": 0.97361684
    },
    {
      "date": "2021-10-15",
      "confidence": 0.9888286
    }
  ]
}

Ploughing marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`events`	List of ploughing events
`start`	Date before a significant rise of baresoil pseudo-probability (BS_PROBA) was detected
`startThreshold`	The first date when the significant rise of BS_PROBA, compared to `startValue`, was detected
`endThreshold`	The first date before `end` when the significant difference of BS_PROBA value compared to `endValue` was detected
`extrema`	Timestamp of the highest BS_PROBA value within the `start` - `end` interval
`end`	Timestamp that marks the end of the ploughing period; has same value as `extrema`
`startValue`	BS_PROBA value at the `start` date
`startThresholdValue`	BS_PROBA value at the `startThreshold` date
`endThresholdValue`	BS_PROBA value at the `endThreshold` date
`extremaValue`	BS_PROBA value at the `extrema` date
`endValue`	BS_PROBA value at the `end` date; has same value as `extremaValue`
`numObservations`	Number of valid observations within the `start` - `end` interval

Example response

{
  "id": "RS20.MARKER.71189-112",
  "markerTypeId": "RS20.CL_MT.S2L2A_PLOUGHING_MARKER",
  "impl" : "EVENT",
  "inferenceId": "RS20.INFERENCE.71189",
  "foiId": "RS20.FOI.112",
  "status": "OK",
  "events" : [ 
    {
      "numObservations" : 4,
      "extremaValue" : 0.8879989,
      "endValue" : 0.8879989,
      "start" : "2020-06-30",
      "end" : "2020-07-30",
      "extrema" : "2020-07-30",
      "endThresholdValue" : 0.393348,
      "startThreshold" : "2020-07-30",
      "startValue" : 0.076752804,
      "startThresholdValue" : 0.8879989,
      "endThreshold" : "2020-07-10"
    } 
  ]
}

Homogeneity marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`classificationCode`	`hypothesisCode` with the highest score
`classificationScore`	`score` of the most probable assumed `hypothesisCode` (value between 0 and 100)
`markerScores`	List of scores per hypothesis
`hypothesisCode`	Assumed homogeneity/heterogeneity of a FOI - "homogeneous" or "heterogeneous"
`score`	The normalised ([0, 100]) representation of probability of the hypothesis being true

Example response

{
  "id": "CY22.MARKER.590-10837450",
  "markerTypeId": "CY22.CL_MT.S2L2A_HOMOGENEITY",
  "impl" : "CLASSIFICATION",
  "inferenceId": "CY22.INFERENCE.590",
  "foiId": "CY22.FOI.10837450",
  "status": "OK",
  "classificationCode": "homogeneous",
  "classificationScore": 98,
  "markerScores": [
    {
      "hypothesisCode": "heterogeneous",
      "score": 2
    },
    {
      "hypothesisCode": "homogeneous",
      "score": 98
    }
  ]
}

Mowing marker (on FOI level)

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`events`	List of mowing events
`start`	The last date before the drop of NDVI was detected
`startThreshold`	The first date when the significant drop of NDVI was detected
`endThreshold`	The first date when the significant difference of NDVI value compared to `extremaValue` was detected.
`extrema`	Timestamp of the lowest NDVI value within the `start` - `end` interval
`end`	The first date after the `extrema` when the NDVI value recovered sufficently compared to `extremaValue`
`startValue`	NDVI value at the `start` date
`startThresholdValue`	NDVI value at the `startThreshold` date
`endThresholdValue`	NDVI value at the `endThreshold` date
`extremaValue`	Lowest NDVI value within the `start` - `end` interval (at the `extrema`)
`endValue`	NDVI value at the `end` date
`numObservations`	Number of valid observations within the `start` - `end` interval
`probability`	Probability of an event

Example response

{
  "id": "CY22.MARKER.589-10837450",
  "markerTypeId": "CY22.CL_MT.S2L2A_MOWING",
  "impl" : "EVENT",
  "inferenceId": "CY22.INFERENCE.589",
  "foiId": "CY22.FOI.10837450",
  "status": "OK",
  "events": [
    {
        "numObservations" : 4,
        "extremaValue" : 0.18152198,
        "endValue" : 0.30097502,
        "probability" : 0.011970464,
        "start" : "2020-08-04",
        "end" : "2020-09-03",
        "extrema" : "2020-08-14",
        "endThresholdValue" : 0.32299966,
        "startThreshold" : "2020-08-14",
        "startValue" : 0.32299966,
        "startThresholdValue" : 0.18152198,
        "endThreshold" : "2020-08-04"
    },
    {
        "numObservations" : 6,
        "extremaValue" : 0.16239251,
        "endValue" : 0.3684666,
        "probability" : 0.030903734,
        "start" : "2020-09-03",
        "extrema" : "2020-09-18",
        "startThreshold" : "2020-09-08",
        "end" : "2020-10-23",
        "endThresholdValue" : 0.30097502,
        "startValue" : 0.30097502,
        "startThresholdValue" : 0.1874948,
        "endThreshold" : "2020-09-03"
    }
  ]
}

Pixel-mowing marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`events`	List of partial mowing events
`ndviBottom`	Lowest NDVI value within the `eventStart` - `eventEnd` interval
`numObservations`	Number of valid observations within the `eventThreshold` - `eventEnd` interval
`ndviStart`	NDVI value on the date before the drop of NDVI was detected (at the `eventStart`)
`eventStart`	The last date before the drop of NDVI was detected
`eventThreshold`	The first date when the drop of NDVI was detected
`ndviDrop`	Difference between the `ndviStart` and `ndviBottom`
`ndviThreshold`	NDVI value on the first date when the drop of NDVI was detected (at the `eventThreshold`)
`daysBetweenStartAndThreshold`	Number of days between `eventStart` and `eventThreshold`
`duration`	Number of days between `eventThreshold` and `eventEnd`
`eventEnd`	End date of the mowing event
`ndviEnd`	NDVI value at the end of the mowing event (at the `eventEnd`)
`eventMask`	Boolean raster mask describing which pixels belong to a cluster
`bottomTimestamp`	Timestamp of the lowest NDVI value within the `eventStart` - `eventEnd` interval

Example response

{
  "id": "TEST.MARKER.9-7422731001",
  "markerTypeId": "TEST.CL_MT.S2L1C_PIXEL_MOWING",
  "inferenceId": "TEST.INFERENCE.9",
  "foiId": "TEST.FOI.7422731001",
  "status": "OK",
  "events": [
    {
      "ndviBottom": 0.6479333,
      "numObservations": 7,
      "ndviStart": 0.84885,
      "eventStart": "2022-06-11",
      "eventThreshold": "2022-06-19",
      "ndviDrop": 0.20091671,
      "ndviThreshold": 0.6937333,
      "daysBetweenStartAndThreshold": 8,
      "duration": 30,
      "eventEnd": "2022-07-19",
      "ndviEnd": 0.75409997,
      "eventMask": [
        [true,false,false],
        [false,false,false]
      ],
      "bottomTimestamp": "2022-06-29"
    }
  ]
}

Pixel-mowing aggregation marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`maxChunkSizePix`	Size (in pixels) of the largest part of FOI with a detected mowing event
`maxChunkRatio`	Relative coverage of the largest part of FOI with a detected mowing event
`mowingDetected`	Flag that is set to true if a FOI has a mowing detected according to specified query
`coverageSizePix`	Count of all pixels with a detected mowing event
`data`	Pixel-mask of mowing event counts
`numPixels`	Number of source pixels inside the FOI's geometry
`coverageRatio`	Relative coverage of all pixels with a detected mowing event

Example response

{
  "id" : "TEST.MARKER.8-6820505001",
  "markerTypeId" : "TEST.CL_MT.S2L1C_PIXEL_MOWING_AGGREGATION",
  "inferenceId" : "TEST.INFERENCE.8",
  "foiId" : "TEST.FOI.6820505001",
  "status" : "OK",
  "maxChunkSizePix" : 10,
  "maxChunkRatio" : 0.8333333,
  "mowingDetected" : true,
  "coverageSizePix" : 10,
  "data" : [ [ -1, 0, 0, 1 ], [ -1, 0, 0, 5 ], [ 0, 0, 0, 4 ] ],
  "numPixels" : 12,
  "coverageRatio" : 0.8333333
}

Similarity marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`classificationCode`	Most similar crop type (crop id)
`declaredAsCode`	Declared crop type (crop id)
`classificationScore`	Score of the most similar crop type (value between 0 and 100)
`markerScores`	List of scores per hypothesis
`hypothesisCode`	Assumed crop type of the target FOI (based on neighboring FOIs)
`score`	The normalised ([0, 100]) representation of the chi2 value of the NDVI time-series difference between the target FOI and the neighboring FOIs (the lower the score, the more similar)

Example response

{
  "id": "CY22.MARKER.593-10837450",
  "markerTypeId": "CY22.CL_MT.S2L2A_SIMILARITY",
  "impl" : "CLASSIFICATION",
  "inferenceId": "CY22.INFERENCE.593",
  "foiId": "CY22.FOI.10837450",
  "status": "OK",
  "classificationCode": "238",
  "declaredAsCode": "40",
  "classificationScore": 20,
  "markerScores": [
    {
      "hypothesisCode": "1",
      "score": 64
    },
    {
      "hypothesisCode": "40",
      "score": 56
    },
    {
      "hypothesisCode": "111",
      "score": 27
    },
    {
      "hypothesisCode": "122",
      "score": 100
    },
    {
      "hypothesisCode": "15",
      "score": 95
    },
    {
      "hypothesisCode": "238",
      "score": 20
    },
    {
      "hypothesisCode": "8",
      "score": 100
    }
  ]
}

Euclidian distance marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`classificationCode`	Most similar crop type (crop id)
`declaredAsCode`	Declared crop type (crop id)
`classificationScore`	Score of the most similar crop type (value between 0 and 100)
`markerScores`	List of scores per hypothesis
`hypothesisCode`	Assumed crop type of the target FOI (based on neighboring FOIs)
`score`	The normalised ([0, 100]) representation of the Median Euclidean distance between the NDVI time-series of the target FOI and the neighboring FOIs having assumed crop type declared (the lower the score, the more similar)
`sameCropCount`	Number of all neighbouring FOIs with the same declared crop type as the target FOI

Example response

{
  "id": "CY22.MARKER.594-10837450",
  "markerTypeId": "CY22.CL_MT.S2L2A_DISTANCE",
  "impl" : "CLASSIFICATION",
  "inferenceId": "CY22.INFERENCE.594",
  "foiId": "CY22.FOI.10837450",
  "status": "OK",
  "classificationCode": "46",
  "declaredAsCode": "40",
  "classificationScore": 56,
  "markerScores": [
    {
      "hypothesisCode": "1",
      "score": 95
    },
    {
      "hypothesisCode": "111",
      "score": 72
    },
    {
      "hypothesisCode": "150",
      "score": 100
    },
    {
      "hypothesisCode": "40",
      "score": 85
    },
    {
      "hypothesisCode": "46",
      "score": 56
    },
    {
      "hypothesisCode": "18",
      "score": 89
    }
  ],
  "sameCropCount": 3
}

Crop-group marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`classificationCode`	Assumed crop group with the highest confidence
`declaredAsCode`	Declared crop group (mapped from the declared crop type)
`classificationScore`	Score of the likeliest assumed crop group (value between 0 and 100)
`markerScores`	List of scores per hypothesis
`hypothesisCode`	Assumed crop group
`score`	Confidence in the assumed crop group (value between 0 and 100)

Example response

{
  "id": "CY22.MARKER.585-10837450",
  "markerTypeId": "CY22.CL_MT.S2L2A_CROP_GROUP_PREDICTION",
  "impl" : "CLASSIFICATION",
  "inferenceId": "CY22.INFERENCE.585",
  "foiId": "CY22.FOI.10837450",
  "status": "OK",
  "classificationCode": "POTATOES",
  "declaredAsCode": "POTATOES",
  "classificationScore": 52,
  "markerScores": [
    {
      "hypothesisCode": "BANANAS",
      "score": 0
    },
    {
      "hypothesisCode": "BARLEY",
      "score": 0
    },
    {
      "hypothesisCode": "CEREALS",
      "score": 2
    },
    {
      "hypothesisCode": "GREENHOUSES",
      "score": 1
    },
    {
      "hypothesisCode": "LAND LYING FALLOW",
      "score": 0
    },
    {
      "hypothesisCode": "LEGUMES",
      "score": 4
    },
    {
      "hypothesisCode": "ORCHARD / VARIUS FRUIT TREES/VEGETABLES",
      "score": 0
    },
    {
      "hypothesisCode": "PERMANENT GRASSLAND",
      "score": 0
    },
    {
      "hypothesisCode": "POTATOES",
      "score": 52
    },
    {
      "hypothesisCode": "VARIOUS VEGETABLES",
      "score": 13
    },
    {
      "hypothesisCode": "WHEAT",
      "score": 2
    },
    {
      "hypothesisCode": "VINEYARDS",
      "score": 0
    }
  ]
}

Land-group marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`classificationCode`	Assumed land use group with the highest confidence
`declaredAsCode`	Declared land use group (mapped from the declared crop type)
`classificationScore`	Score of the likeliest assumed land use group (value between 0 and 100)
`markerScores`	List of scores per hypothesis
`hypothesisCode`	Assumed land use group
`score`	Confidence in the assumed land use group (value between 0 and 100)

Example response

{
  "id": "CY22.MARKER.586-10837450",
  "markerTypeId": "CY22.CL_MT.S2L2A_LAND_COVER",
  "impl" : "CLASSIFICATION",
  "inferenceId": "CY22.INFERENCE.586",
  "foiId": "CY22.FOI.10837450",
  "status": "OK",
  "classificationCode": "ARABLE LAND",
  "declaredAsCode": "ARABLE LAND",
  "classificationScore": 100,
  "markerScores": [
    {
      "hypothesisCode": "ARABLE LAND",
      "score": 100
    },
    {
      "hypothesisCode": "GRASSLAND (PERMANENT PASTURE)",
      "score": 0
    },
    {
      "hypothesisCode": "GREENHOUSE",
      "score": 0
    },
    {
      "hypothesisCode": "PERMANENT CROPS",
      "score": 0
    }
  ]
}

Mean-NDVI marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`value`	Mean NDVI value of all valid observations per FOI

Example response

{
    "id": "CY22.MARKER.592-10837450",
    "markerTypeId": "CY22.CL_MT.S2L2A_AGGREGATION_MEAN_NDVI",
    "impl" : "AGGREGATION",
    "inferenceId": "CY22.INFERENCE.592",
    "foiId": "CY22.FOI.10837450",
    "status": "OK",
    "value": 0.5653076
}

Greening-harvest marker

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`impl`	Marker class
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`eventComposites`	List of rise-fall pairs
`rise.start`	Date before a significant rise of NDVI was detected; start of the greening period
`rise.startThreshold`	The first date when the significant rise of NDVI, compared to `rise.startValue` was detected
`rise.endThreshold`	The first date before `rise.end` when the significant difference of NDVI value compared to `rise.endValue` was detected
`rise.extrema`	Timestamp within the greening period when the NDVI value is the highest
`rise.end`	Timestamp that marks the end of the greening period; has same value as `rise.extrema`
`rise.startValue`	NDVI value at the `rise.start`
`rise.startThresholdValue`	NDVI value at the `rise.startThreshold`
`rise.endThresholdValue`	NDVI value at the `rise.endThreshold`
`rise.extremaValue`	NDVI value at the `rise.extrema`
`rise.endValue`	NDVI value at the `rise.end`; has same value as `rise.extremaValue`
`rise.numObservations`	Number of valid observations between the start and the end of the greening period
`fall.start`	Date before a significant NDVI drop was detected; start of the harvest period
`fall.startThreshold`	The first date when the significant drop of NDVI, compared to `fall.startValue` was detected
`fall.endThreshold`	The first date before `fall.end` when the significant difference of NDVI value compared to `fall.endValue` was detected.
`fall.extrema`	Timestamp within the harvest period when the NDVI value is the lowest
`fall.end`	Timestamp that marks the end of the harvest period; has same value as `fall.extrema`
`fall.startValue`	NDVI value at the `fall.start`
`fall.startThresholdValue`	NDVI value at the `fall.startThreshold`
`fall.endThresholdValue`	NDVI value at the `fall.endThreshold`
`fall.extremaValue`	NDVI value at the `fall.extrema`
`fall.endValue`	NDVI value at the `fall.end`; has same value as `fall.extremaValue`
`fall.numObservations`	Number of valid observations between the start and the end of the harvest period

Example response

{
  "id": "TEST.MARKER.91-6727959001",
  "markerTypeId": "TEST.CL_MT.S2L2A_GREENING_HARVEST",
  "impl" : "EVENT_COMPOSITE",
  "inferenceId": "TEST.INFERENCE.91",
  "foiId": "TEST.FOI.6727959001",
  "status": "OK",
  "eventComposites": [
    {
      "rise" : {
        "endValue" : 0.83880246,
        "endThreshold" : "2020-04-01",
        "startValue" : 0.6217497,
        "end" : "2020-04-16",
        "extrema" : "2020-04-16",
        "startThreshold" : "2020-03-12",
        "numObservations" : 7,
        "endThresholdValue" : 0.77352065,
        "startThresholdValue" : 0.7250762,
        "extremaValue" : 0.83880246,
        "start" : "2020-03-02"
      },
      "fall" : {
        "extrema" : "2020-09-18",
        "endThreshold" : "2020-09-03",
        "end" : "2020-09-18",
        "endValue" : 0.16239251,
        "startValue" : 0.83880246,
        "startThreshold" : "2020-07-05",
        "start" : "2020-04-16",
        "startThresholdValue" : 0.36374354,
        "numObservations" : 10,
        "endThresholdValue" : 0.30097502,
        "extremaValue" : 0.16239251
      }
    }
  ]
}

Evaluation

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`evaluation`	Result of the evaluation of the given condition(s) (true/false)

Example response

{
  "id" : "TEST.MARKER.6-4981068",
  "markerTypeId" : "TEST.CL_MT.S2L1C_EVALUATION",
  "inferenceId" : "TEST.INFERENCE.6",
  "foiId" : "TEST.FOI.4981068",
  "status" : "OK",
  "evaluation" : true
}

Count aggregattion

Key	Description
`id`	Marker id
`markerTypeId`	Marker type id
`inferenceId`	Inference id
`foiId`	FOI (Feature Of Interest) id
`status`	Marker status ("OK", "NOT_VALID" or "NOT_EXECUTED")
`count`	Count of valid (according to a given condition) occurences, e.g. number of valid observatons, number of observations when the FOI's mean NDVI was above some threshold, etc.

Example response

{
  "id" : "TEST.MARKER.90-4105747",
  "markerTypeId" : "TEST.CL_MT.S2L1C_AGGREGATION_VALID_FULL",
  "inferenceId" : "TEST.INFERENCE.90",
  "foiId" : "TEST.FOI.4105747",
  "status" : "OK",
  "count" : 10
}