Vegetation Index (VI) map

This page shows you how to order a Vegetation Index (VI) map, resolve or define the index it's built from, and use VI's two bulk-ordering paths. See ANA Precision Farming APIs for the base URL, authentication, shared field-boundary rules, credit model, and general status codes — this page only covers what's specific to VI.

Endpoints

Method	Path	Purpose
POST	`maps/vegetation-index-map/orders/`	Create an order (single or bulk — see below)
GET	`maps/vegetation-index-map/orders/{ORDER_ID}/`	Retrieve an order
GET	`maps/vegetation-index-map/orders/`	List orders

Auth

Send your access token as a bearer token, as described in ANA Precision Farming APIs.

Required permission: vi.create for create, vi.view for list/retrieve. A missing permission returns HTTP 403 with a structured body: {"code": "permission_denied", "message": "...", "details": {"required_permission", "action", "resource"}}.

Request fields

A VI order also accepts the fields shared by every ANA map product — field_uuid/field_boundary, output_data_type, no_of_classes, is_background — documented in ANA Precision Farming APIs. The table below covers only the fields specific to VI.

Field	Type	Required	Default	Notes
`image_dates`	array of dates	Yes	—	A list, not a single date — this is the field that drives bulk behavior (see below). A bare single date string is automatically wrapped into a 1-item list if you send it that way.
`index_code`	string	No	`"NDVI"` if nothing else is given	If you give a recognized code matching an existing index in Spacenus's catalog, `index_name`/`index_formula`/`index_description` are auto-filled from that catalog entry.
`index_name`	string	No	—	If only a name is given (no code/formula), a custom `index_code` is auto-generated from it.
`index_formula`	string	No	—	Becomes required if your `index_code` doesn't match any known/catalog index — i.e. defining a genuinely custom index requires supplying its formula.
`index_description`	string	No	—	Optional free-text description for a custom index.

Index resolution, in plain terms: give nothing, and you get NDVI. Give a known index_code or index_name that matches an entry in Spacenus's index catalog, and the rest (index_name/index_formula/index_description) is filled in for you automatically. Give a code or name that isn't recognized, and you must also supply index_formula yourself — that's what defines a genuinely custom index.

Bulk ordering — two ways to trigger it

VI has two distinct ways to get a 202 bulk response — more than any other ANA product.

1. Send a JSON array

POST an array of up to 5 request objects (each with the same shape described above) to the same orders/ endpoint. This is the same bulk mechanism NRX uses — no separate URL, just an array body instead of a single object.

2. Send multiple `image_dates` in one object

Send a single request object whose image_dates array has more than one date. The server automatically expands it into one order per date — a single object with 3 dates in image_dates becomes a 3-item bulk order, even though you never sent a JSON array. This behavior is unique to VI among the ANA products.

Either path is capped at 5 total items — the raw array length for method 1, or the expanded date count for method 2. Exceeding the cap returns HTTP 400 with the message "Bulk VI processing supports up to 5 items at a time." Both paths return HTTP 202 Accepted on success, using the bulk envelope shape described in ANA Precision Farming APIs.

maps/vegetation-index-map/bulk-orders/ is a separate, read-only endpoint for listing/retrieving past bulk orders only — it does not accept POST requests to create new ones. To create a bulk order, use either method above against the regular orders/ endpoint.

Status codes specific to VI

Status	Trigger
200	Order created (single, non-bulk request — one object with a single `image_dates` entry).
202	Bulk order accepted — either an array body, or a single object whose `image_dates` had more than one date.
400	Validation failure — for example a missing `image_dates`, an unrecognized `index_code` with no `index_formula`, or exceeding the 5-item bulk cap.
402	Insufficient wallet credit.
404	`field_uuid`/`field_boundary` didn't resolve to a field.
409	A VI map for this field, date, and index already exists and is active — see the dedup notes below.
500	Internal error building or dispatching the order for processing.

A duplicate VI request (HTTP 409, below) 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.

Deduplication only applies to standard index codes (NDVI, SAVI, EVI, NDMI, NDREI). A custom index_formula order is never deduplicated — re-ordering the same custom index for the same field and date always creates a new order, even if an identical one already exists and is active.
VI also has no "recently processing" grace window, unlike NRX's 20-minute window — only orders that have already reached active status count as duplicates. That means two concurrent requests for the same field, date, and index can both proceed if neither has finished processing yet.

Retrieve response

In addition to the fields common to every ANA order, a VI order's retrieve response includes:

Field	Notes
`map_type`	`"vi"`
`status`	One of `pending`, `processing`, `active`, `failed`.
`tif_url`	Populated once the order completes.
`application_map_url`	Populated once the order completes.
`json_response`	Raw processing result payload.
`map_date`	The image date this map was generated from.
`index_code` / `index_name` / `index_formula` / `index_description`	The resolved index identity for this order (see request-field resolution logic above).

Completion event

vi_order_completed is published when an order finishes. On success it includes order_id, field_id, field_uuid, company_id, and map_uuid. A failed order includes an error string instead. See ANA Precision Farming APIs for general event-handling guidance.

Examples

Create a single-date order

curl -X POST "https://backend.spacenus.de/api/v1.2/maps/vegetation-index-map/orders/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_uuid": "FIELD_UUID",
    "image_dates": ["2026-07-15"],
    "index_code": "NDVI"
  }'

Response:

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

Bulk order via JSON array

curl -X POST "https://backend.spacenus.de/api/v1.2/maps/vegetation-index-map/orders/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {"field_uuid": "FIELD_UUID", "image_dates": ["2026-06-01"], "index_code": "NDVI"},
    {"field_uuid": "FIELD_UUID", "image_dates": ["2026-06-15"], "index_code": "SAVI"}
  ]'

Response:

{
  "status": "success",
  "message": "Bulk VI map processing started successfully.",
  "data": {
    "id": 214,
    "status": "processing",
    "total_items": 2,
    "items": [
      {"item_uuid": "b1e2c3a4-...", "status": "processing"},
      {"item_uuid": "c4d5e6f7-...", "status": "processing"}
    ]
  }
}

Retrieve an order

curl "https://backend.spacenus.de/api/v1.2/maps/vegetation-index-map/orders/ORDER_ID/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "status": "success",
  "message": "Request successful.",
  "data": {
    "order_id": 5310,
    "map_type": "vi",
    "status": "active",
    "map_date": "2026-07-15",
    "index_code": "NDVI",
    "index_name": "Normalized Difference Vegetation Index",
    "index_formula": "(NIR - RED) / (NIR + RED)",
    "index_description": null,
    "tif_url": "https://.../vi_5310.tif",
    "application_map_url": "https://.../vi_5310_app.geojson",
    "json_response": { "map_uuid": "vi-5310-uuid" }
  }
}

Endpoints

Auth

Request fields

Bulk ordering — two ways to trigger it

1. Send a JSON array

2. Send multiple image_dates in one object

Status codes specific to VI

Retrieve response

Completion event

Examples

Create a single-date order

Bulk order via JSON array

Retrieve an order

2. Send multiple `image_dates` in one object