Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/marker-service-api/) # Marker Service API ## API Overview The Marker service API is a RESTful API interface to various markers. You can browse the reference docs [here](https://am-pilot.sinergise.com/marker/swagger-ui.html). 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 | ![](/data/area-monitoring/marker-service-api/RiseEvent.webp) ### 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 | ![](/data/area-monitoring/marker-service-api/MowingEvent.webp) ### 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 | ![](/data/area-monitoring/marker-service-api/RiseFallEvent.webp) ### 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, for example, 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 } ```