Nitrogen Recommendation Map (NRX)

Order a Nitrogen Recommendation Map for a field to get zone-based nitrogen application guidance derived from recent satellite imagery.

This page covers only what's specific to NRX. 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/nitrogen-recommendation-map/orders/`	Create an order (also accepts a bulk array — see below)
GET	`/maps/nitrogen-recommendation-map/orders/ORDER_ID/`	Retrieve a single order
GET	`/maps/nitrogen-recommendation-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	`nrx.create`
List / Retrieve	`nrx.view`

A request that has a valid token but lacks the required permission gets an HTTP 403 with a structured body instead of the generic envelope:

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

Request fields

NRX orders also take the shared fields (field_uuid / field_boundary, output_data_type, no_of_classes, is_background) described in ANA Maps Overview — they aren't repeated here. In addition, NRX requires:

Field	Type	Required	Default	Notes
`crop_type`	string (enum)	Yes	—	One of: `wheat`, `rapeseed`, `corn`, `barley`, `rye`, `triticale`, `cotton`, `red cabbage`, `white cabbage`, `chinese cabbage`, `cauliflower`.
`image_date`	date (`YYYY-MM-DD`)	Conditionally required	—	Provide this OR both `start_date` and `end_date`.
`start_date`	date (`YYYY-MM-DD`)	Conditionally required	—	Use together with `end_date` as an alternative to `image_date`.
`end_date`	date (`YYYY-MM-DD`)	Conditionally required	—	Use together with `start_date`.

Field naming note: this endpoint uses crop_type. The Pre-season Nitrogen Recommendation endpoint uses a differently-named crop field with a different — and larger — enum. Don't assume the two are interchangeable when reusing form or mapping code across both integrations.

Bulk ordering

NRX supports bulk ordering: POST a JSON array of up to 5 request objects (each shaped like the single-object body above) to this same orders/ endpoint. A bulk request returns 202 Accepted instead of 200 OK — see ANA Maps Overview for the exact bulk response envelope shape and per-item result semantics.

/maps/nitrogen-recommendation-map/bulk-orders/ is a separate, read-only endpoint — it only lists and retrieves past bulk orders. You cannot create a bulk order there; bulk creation always goes through orders/ with an array body.

Status codes

Status	Trigger
200	Order created (single, non-bulk request).
202	Bulk order accepted.
400	Validation failure — e.g. missing `crop_type`, an unrecognized crop, or neither `image_date` nor `start_date`/`end_date` provided. Also raised if a bulk array exceeds 5 items.
402	Insufficient wallet credit — see the credit model in ANA Maps Overview.
403	Missing `nrx.create` (create) or `nrx.view` (list/retrieve) permission.
404	`field_uuid` / `field_boundary` didn't resolve to a field, or no satellite image is available for the requested `image_date`.
409	A map for this exact field and `image_date` already exists with status `active`, or one is still `processing` and was created within the last 20 minutes. The response body includes the existing map's data — treat this as a success, not an error.
500	Internal error building or dispatching the order to cloud processing.

A duplicate NRX request (409, above) never costs you 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 ANA Maps Overview for the full credit model.

Create request

curl -X POST https://backend.spacenus.de/api/v1.2/maps/nitrogen-recommendation-map/orders/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_uuid": "FIELD_UUID",
    "crop_type": "wheat",
    "image_date": "2026-05-12",
    "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/nitrogen-recommendation-map/orders/ORDER_ID/ returns the generic order envelope (see ANA Maps Overview) plus these NRX-specific fields:

Field	Notes
`map_type`	Always `"nrx"`.
`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": "nrx",
    "status": "active",
    "tif_url": "https://.../ORDER_ID.tif",
    "application_map_url": "https://.../ORDER_ID_application.geojson",
    "json_response": { "...": "..." }
  }
}

Completion event

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

nrx_order_completed is the one completion event of the five map/profile products that never includes map_uuid — not even on success. Don't build a handler that assumes map_uuid is present; use tif_url / application_map_url from the retrieve response instead.