Soil Productivity Map (SPM)

Order a Soil Productivity Map for a field to get a zone-based productivity classification computed from a multi-year satellite history — no crop type or date range to supply.

This page covers only what's specific to SPM. For the base URL, authentication, the shared request fields, the wallet credit model, bulk-ordering mechanics, and general status codes, see ANA Maps Overview.

Endpoints

Method	Path	Purpose
POST	`/maps/soil-productivity-map/orders/`	Create an order (single object only — see below)
GET	`/maps/soil-productivity-map/orders/ORDER_ID/`	Retrieve a single order
GET	`/maps/soil-productivity-map/orders/`	List orders

Auth

Requires a Bearer token — see ANA Maps Overview for how to obtain and send one.

Each action also requires a dynamic permission on top of the token:

Action	Required permission
Create	`spm.create`
List / Retrieve	`spm.view`

A request that has a valid token but lacks the required permission gets an HTTP 403 with the same structured permission_denied body used across ANA endpoints:

{
  "code": "permission_denied",
  "message": "You do not have permission to access this resource.",
  "details": {
    "required_permission": "spm.create",
    "action": "create",
    "resource": "SpmMapOrderViewSetV2"
  }
}

Request fields

SPM has no product-specific fields beyond the shared ones (field_uuid / field_boundary, output_data_type, no_of_classes, is_background) documented in ANA Maps Overview — there is no request field table specific to SPM.

No crop_type and no date range needed. SPM computes a fixed 5-year satellite lookback window server-side, so the request body is just the shared fields.

No bulk support

SPM does not support bulk ordering. POST /maps/soil-productivity-map/orders/ only accepts a single request object — sending a JSON array is not supported for this endpoint (unlike NRX or the other bulk-capable ANA products, see ANA Maps Overview).

Status codes

Status	Trigger
200	Order created.
400	Validation failure on the shared fields — e.g. neither (or both) of `field_uuid` / `field_boundary` given, or the field's area is outside the 0.1–10,000 hectare range.
402	Insufficient wallet credit.
403	Missing `spm.create` (create) or `spm.view` (list/retrieve) permission.
404	`field_uuid` / `field_boundary` didn't resolve to a field.
409	A soil productivity map for this field already exists. Deduplication uses two configurable windows (defaults: a map still `processing` and created within the last 360 minutes, or a map `active` and requested within the last 120 days for that field). The response body includes the existing order/map data — treat this as a success, not an error.
500	Internal error preparing the satellite dataset or dispatching the order to cloud processing.

A duplicate SPM request (409, above) doesn't cost extra credit. A field is only ever charged once — on its first successful ANA order, across any of the five products — and a request can only come back as a duplicate if an earlier order for that field already exists, meaning the charge already happened on that earlier order. See the credit model in ANA Maps Overview.

Create request

curl -X POST https://backend.spacenus.de/api/v1.2/maps/soil-productivity-map/orders/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_uuid": "FIELD_UUID",
    "output_data_type": 1,
    "no_of_classes": 5,
    "is_background": true
  }'

Response:

{
  "status": "success",
  "message": "Map processing started successfully.",
  "data": {
    "order_id": "ORDER_ID",
    "status": "processing"
  }
}

Retrieve response

GET /maps/soil-productivity-map/orders/ORDER_ID/ returns the generic order envelope (see ANA Maps Overview) plus these SPM-specific fields:

Field	Notes
`map_type`	Always `"spm"`.
`status`	One of `pending`, `processing`, `active`, `failed`.
`tif_url`	GeoTIFF output, once `active`.
`application_map_url`	Zone application map output, once `active`.
`json_response`	Raw provider response payload.

{
  "status": "success",
  "message": "Order retrieved successfully.",
  "data": {
    "order_id": "ORDER_ID",
    "map_type": "spm",
    "status": "active",
    "tif_url": "https://.../ORDER_ID.tif",
    "application_map_url": "https://.../ORDER_ID_application.geojson",
    "json_response": { "...": "..." }
  }
}

Completion event

When an SPM order reaches a terminal state, an spm_order_completed event fires on the same real-time channel described in ANA Maps Overview. Its payload includes order_id, field_id, field_uuid, company_id, and — unlike NRX — map_uuid on success.

map_uuid is only present once a map has actually been generated, so it's omitted on a failure outcome even for SPM. Use type ("success"/"error") on the event, or re-check the retrieve endpoint's status, before relying on map_uuid being there.