Precision Farming APIs

This page walks you through the concepts, request/response shapes, and rules shared by every ANA precision-farming map and profile product, so you can order any of them correctly on the first try.

Last updated: 2026-08-19

ANA is Spacenus's family of precision-farming map and profile products — five order endpoints that all share the same base URL, authentication, field-boundary rules, credit model, and status codes. This page documents everything they have in common. Each product also has its own page with its request/response fields, dedup rules, and edge cases.

Before you start

Register the field you want a map for in Farm Management, if you haven't already.
Grab that field's FIELD_UUID — you'll pass it (or an equivalent GeoJSON boundary) on every order request.
Have a company-scoped access token (YOUR_TOKEN) ready to send as a bearer token on every request.

Base URL and authentication

All ANA endpoints are mounted under:

https://backend.spacenus.de/api/v1.2/

Every request must be authenticated. Send your access token as a bearer token:

Authorization: Bearer YOUR_TOKEN

As an alternative to the bearer token, these endpoints also accept an API key passed as a query parameter (API_KEY). Lead with the bearer token in your integration — it's the primary supported flow — and fall back to the API key only where a bearer token isn't practical to use.

Products at a glance

Product	What it gives you	Order endpoint
Nitrogen Recommendation Map (NRX)	Zone-wise nitrogen application recommendation map	`POST maps/nitrogen-recommendation-map/orders/`
Pre-season Nitrogen Recommendation (PNRX)	Pre-season nitrogen recommendation derived from fertilization history	`POST maps/preseason-nitrogen-recommendation/orders/`
Soil Productivity Map (SPM)	Zone-wise soil productivity map from a 5-year satellite lookback	`POST maps/soil-productivity-map/orders/`
Vegetation Index Map (VI)	Vegetation index map (NDVI by default, or a custom index)	`POST maps/vegetation-index-map/orders/`
Vegetation Index Profile	Season-long vegetation index time series for a field	`POST profiles/vegetation-index-profile/orders/`

The links above use relative Markdown links to the sibling pages in this same folder. If your ReadMe project doesn't resolve relative .mdx links this way, look up each page by its title in the docs navigation instead — the endpoint paths in the table are accurate either way.

How it works

1. Create an order

POST to the product's orders/ endpoint with a field_uuid or field_boundary. The order is accepted and processing starts asynchronously.

2. Track processing

Poll GET .../orders/{ORDER_ID}/, or listen for the product's completion event, to see when the order finishes.

3. Download the result

Once the order completes, fetch the resulting map or profile data from the completed order.

Fields shared by every map-order create request

The following fields apply to NRX, SPM, PNRX, and VI create requests (not VI Profile — see that product's own page for its request shape).

Field	Type	Required	Default	Notes
`field_uuid`	string	Conditionally required	—	Provide this OR `field_boundary`, never both, never neither. Must reference an existing field.
`field_boundary`	object (GeoJSON) or JSON string	Conditionally required	—	Alternative to `field_uuid`. Expected shape: a GeoJSON `FeatureCollection` with `features[0].geometry.coordinates`.
`output_data_type`	integer (enum)	No	`1`	`1` = zone-wise GeoJSON, `2` = zone-wise GeoTIFF, `3` = pixel-wise GeoTIFF.
`no_of_classes`	integer	No	`5`	Must be between 1 and 10.
`is_background`	boolean	No	`true`	See note below.

The output_data_type choice labels in the API schema are worded around soil productivity output (for example, "Zone-wise Soil productivity map Geojson") for historical reasons. In practice this field applies the same way across all four map products — NRX, SPM, PNRX, and VI — not just SPM.

The underlying schema's own default for is_background is false, but every one of the four create endpoints (NRX, SPM, PNRX, VI) explicitly overrides it to true. In practice you'll get true unless you send false yourself.

Field boundary validation

Whether you supply a field_uuid or a field_boundary, the resolved area must be greater than 0.1 hectares and less than 10,000 hectares. Requests outside that range are rejected as invalid.

Create-response envelope

A successful, single (non-bulk) order returns HTTP 200 with this shape:

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

The exact wording of message varies slightly per product — for example, VI Profile returns "VI Profile processing started successfully." Check each product's own page for its exact response text.

Credit model

The first time you successfully order any of the four map products (NRX, SPM, PNRX, VI) for a given field, that field is charged at a flat rate of 3 credits per hectare of the field's area. Once a field has been charged once, every subsequent order for that same field — across any of the five ANA products, not just the one you originally ordered — is free. This is a per-field, cross-product credit model, not a per-product price. If your company's wallet balance is insufficient to cover a charge, the request fails with HTTP 402 Payment Required.

Duplicate orders don't cost extra credit. A field is only ever charged once — on its first successful ANA order, across any of the five products. A request can only come back as a duplicate (409) if an earlier order for that same field already exists, and that earlier order is what triggered the one-time charge — the duplicate request itself isn't charged again.

Bulk ordering

Bulk ordering is only available for NRX and VI. SPM, PNRX, and VI Profile do not support bulk ordering at all.

To place a bulk order, send a JSON array instead of a single object to the same orders/ endpoint — there's no separate URL for bulk requests. A bulk request is capped at 5 items, enforced both on the length of the array you send and, for VI specifically, on the expanded per-date item count after processing (see the Vegetation Index Map page for VI's additional "single object with multiple image_dates auto-expands into a bulk order" behavior).

A successful bulk request returns HTTP 202 Accepted with this shape:

{
  "status": "success",
  "message": "Bulk NRX map processing started successfully.",
  "data": {
    "id": 91,
    "status": "processing",
    "total_items": 3,
    "items": [
      {"item_uuid": "...", "status": "processing"},
      {"item_uuid": "...", "status": "skipped"},
      {"item_uuid": "...", "status": "failed"}
    ]
  }
}

maps/nitrogen-recommendation-map/bulk-orders/ and maps/vegetation-index-map/bulk-orders/ are separate, read-only endpoints — they only list or retrieve past bulk orders. POSTing to them does not create anything. To create a bulk order, POST a JSON array to the regular .../orders/ endpoint for that product.

Status codes

Status	Meaning here
200	Single (non-bulk) order created successfully.
202 Accepted	Bulk order accepted for processing (array body, or for VI, a single object that expanded into multiple items).
400 Bad Request	Request body failed validation — applies the same way to single-object and bulk/array bodies.
402 Payment Required	Insufficient wallet credit to cover the charge for this order.
404 Not Found	The given `field_uuid`/`field_boundary` didn't resolve to a field, or (NRX) no satellite image is available for the requested date.
409 Conflict	A duplicate order already exists for this field (see each product's page for its own dedup window/rule) — the response includes the existing order's data; treat as success.
422 Unprocessable Entity	Pre-season Nitrogen Recommendation only: the field is outside the region required for the requested crop (see the PNRX page).
500	An internal error occurred creating or dispatching the order (for example, satellite dataset preparation or cloud-processing dispatch failed).

Completion events

Each product publishes a real-time completion event when an order finishes:

Product	Completion event	Includes `map_uuid`?
NRX	`nrx_order_completed`	No — never included on this event
PNRX	`pnrx_order_completed`	Yes
SPM	`spm_order_completed`	Yes
VI	`vi_order_completed`	Yes
VI Profile	`vi_profile_completed`	N/A — profiles don't have a map

Every event includes order_id, field_id, field_uuid, and company_id. A failed order includes an error string instead of the success fields.

If you're not listening for events, poll GET .../orders/{ORDER_ID}/ instead.

The exact event-delivery mechanics — websocket vs. webhook transport, connection setup, payload framing — are out of scope for this page. See the SPACENUS_SERVICES_PROCESS_EVENTS_INTEGRATION_GUIDE.md guide, one level up in the integration-guides/ folder, for that detail.

What's next

Head to the page for the specific product you're integrating — NRX, PNRX, SPM, VI Map, or VI Profile — for its exact request fields, response text, and dedup rules. Everything on this page applies underneath all five.

Precision Farming APIs

Before you start

Base URL and authentication

Products at a glance

How it works

Fields shared by every map-order create request

Field boundary validation

Create-response envelope

Credit model

Bulk ordering

Status codes

Completion events

What's next

What’s Next

What’s Next