Stratification Workflow

Soil stratification is a six-step pipeline: place an order against an AOI, stratify it into zones, generate a
sample plan from the stratified map, optionally check the plan's minimum detectable difference (MDD), then save
whichever draft map and/or plan you want to keep. This page documents all six actions in the order you'll
normally call them. See SatMRV API for the base URL, authentication, and response envelope
shape — this page only covers what's specific to the stratification workflow.

Auth

Send your access token as a bearer token, as described in SatMRV API.

All six actions on this page require IsAuthenticated plus HasDynamicPermission — there is no separate
IsSubscribed permission check on these specific actions, unlike the AOI endpoints. The one exception is
step 1, place-order, which does its own manual subscription check in the view body (see below) and returns
HTTP 400 rather than 403 if your company isn't subscribed.

The pipeline

Step	Method	Path	Permission
Place order	POST	`stratification/data-processing/place-order/`	`stratification_workflow.create`
Stratify	POST	`stratification/stratify/`	`stratification_workflow.create`
Generate sample plan	POST	`stratification/stratify/plan/`	`stratification_workflow.view`
Check MDD	POST	`stratification/stratify/plan/mdd/`	`stratification_workflow.view`
Save sample plan	POST	`stratification/stratify/plan/save/`	`stratification_workflow.edit`
Save stratification map	POST	`stratification/stratify/save/`	`stratification_workflow.edit`

1. Place a stratification order

POST stratification/data-processing/place-order/

Places a stratification data order for an AOI. This is where wallet credit is actually charged and the
once-per-year-per-AOI limit is enforced. Once the order exists, see
Stratification Data Orders for what the resulting order record looks
like.

Required permission: stratification_workflow.create.

Field	Type	Required	Notes
`aoi_uuid`	string	Yes	The AOI to order stratification data for.

Status	Trigger
200	Order placed successfully.
400	AOI not found for your company; only one stratification map order is allowed per AOI per year; insufficient wallet balance (`"Insufficient Credit Balance"`); your company isn't subscribed to "Stratification Map".
500	The wallet credit update failed while placing the order.

Placing an order is the only chargeable step in this workflow — the once-per-year limit and the wallet charge
are both scoped to the AOI, not to any individual downstream stratify/plan call.

2. Stratify

POST stratification/stratify/

Runs stratification on a placed order, producing zones.

Required permission: stratification_workflow.create.

Field	Type	Required	Default	Notes
`data_uuid`	string	Yes	—	Must reference an existing stratification data order.
`layers`	array	No	—	Values from: `HWSDB_SOIL_TYPE`, `IPCC_CLIMATE_ZONE`, `BMA`, `CLAY_0-5`, `SG_WA_CLAY_0-30`, `TWI`, `DEM`, `YEARLY_TEMPERATURE_2M_MEAN`, `YEARLY_PRECIPITATION_SUM`.
`number_of_zones`	integer	No	—
`area_size`	float	No	—
`output_data_type`	integer	No	`1`	`2` returns a downloadable GeoJSON file instead of a JSON body.
`use_recent_if_empty`	boolean	No	`true`	Reuses a cached recent result instead of recomputing, if one exists.

Status	Trigger
200	Stratification completed.
400	Validation failure, or `data_uuid` not found.
422	`"Map unavailable for provided parameters"` — the external stratification pipeline failed for these inputs.

3. Generate a sample plan

POST stratification/stratify/plan/

Generates a sample plan from a stratified map.

Despite being a POST that creates something, this action's permission slug is stratification_workflow.view,
not .create — that's the actual slug enforced, not an assumption.

Field	Type	Required	Default	Notes
`data_uuid`	string	Yes	—
`number_of_samples`	integer	No	—	Must be ≥ 0.
`sampling_seed`	integer	No	—	Must be ≥ 0.
`boundary_offset`	integer	No	—	Must be ≥ 0.
`zone_offset`	integer	No	—	Must be ≥ 0.
`samples_offset`	integer	No	—	Must be ≥ 0.
`output_data_type`	integer	No	`1`	`1` or `2`.
`map_tag`	string	No	—	Omit to use your current unsaved draft map. If supplied, it must already have an unsaved plan slot, else 400 (`"No unsaved sample plan exists under map '...'"`).
`use_recent_if_empty`	boolean	No	`true`

Status	Trigger
200	Sample plan generated.
400	Validation failure — including any of `number_of_samples`/`sampling_seed`/`boundary_offset`/`zone_offset`/`samples_offset` being negative, or an invalid `map_tag`.
422	`"Map unavailable for provided parameters"` (same pattern as step 2).

4. Check minimum detectable difference (MDD)

POST stratification/stratify/plan/mdd/

Required permission: stratification_workflow.view.

Field	Type	Required	Default	Notes
`data_uuid`	string	Yes	—
`plan_tag`	string	No	—
`expected_increase`	integer	No	`5`
`significance`	float	No	—
`power`	float	No	—
`output_file_type`	integer	No	`1`	Must be `1` or `2`, else 400 (`"Invalid output file type"`).

Status	Trigger
200	MDD computed.
400	Validation failure — including an `output_file_type` outside `1`/`2`.
422	`"MDD unavailable"` on any pipeline exception.

5. Save a sample plan

POST stratification/stratify/plan/save/

Converts a draft sample plan into a permanent record. Required permission: stratification_workflow.edit.

Field	Type	Required	Notes
`data_uuid`	string (UUID)	Yes
`map_tag`	string	Yes	Must reference an unsaved plan under that tag, else a 400 "already been saved"-style error.

Status	Trigger
200	Plan saved.
400	Validation failure — invalid `data_uuid`/`map_tag`, or the plan under that tag has already been saved.

6. Save a stratification map

POST stratification/stratify/save/

Converts a draft stratification map into a permanent record. Required permission: stratification_workflow.edit.

Field	Type	Required	Notes
`data_uuid`	string	Yes
`name`	string	No

Status	Trigger
200	Map saved.
400	Validation failure — invalid `data_uuid`, or the map has already been saved.

map_tag/plan_tag, in plain terms: these identify a specific draft result before you decide to keep it.
Omit them and the system finds your most recent unsaved draft automatically; supply one explicitly if you're
juggling multiple drafts and need to be precise about which one you're acting on. Saving (the .../save/
actions) converts a draft into a permanent record, visible afterward via the Saved Maps endpoints — see
Saved Maps.

Examples

Place a stratification order

curl -X POST "https://backend.spacenus.de/api/v1.2/sat-mrv/stratification/data-processing/place-order/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi_uuid": "AOI_UUID"
  }'

Response:

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "data_uuid": "DATA_UUID"
  }
}

Generate a sample plan

curl -X POST "https://backend.spacenus.de/api/v1.2/sat-mrv/stratification/stratify/plan/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data_uuid": "DATA_UUID",
    "number_of_samples": 40,
    "zone_offset": 2
  }'

Response:

{
  "status": "success",
  "message": "Map processed successfully.",
  "data": {
    "map_uuid": "DATA_UUID",
    "metadata": {
      "number_of_samples": 40,
      "zone_offset": 2
    },
    "sample_plan": {
      "map_tag": "MAP_TAG",
      "plan_tag": "PLAN_TAG",
      "samples": [
        {"latitude": 52.5013, "longitude": 13.4029, "zone_id": 1},
        {"latitude": 52.5041, "longitude": 13.4102, "zone_id": 2}
      ]
    }
  }
}