Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Upload and Analyzing Plots

This guide walks you through how to upload plots, request analyses, and track their status via the TradeAware Public API.

Please note if you use fields that are not supported, your request will still proceed and the unsupported fields will be stripped out.

Use Case #1: Upload Geolocation Information

Upload a single plot using either traditional JSON or GeoJSON format.

This allows you to register a field or location for compliance and monitoring purposes.

Option A: Upload a Single Plot (JSON or GeoJSON)

Endpoint: POST https://api.tradeaware.live-eo.com/plots

Headers

Authorization: Bearer <token>
Content-Type: application/json           # or application/geo+json
Accept: application/json                 # or application/geo+json

Required Fields:

  • commodities: Specify the crops grown on this plot (e.g., rubber, palm oil).

  • name: A descriptive name for the plot to aid identification.

  • geometry: Location of the plot in GeoJSON format. Supported types: Polygon, MultiPolygon, and Point (for plots ≤ 4ha).

  • description: Additional plot details for easy referencing.

Optional Fields:

  • customData : custom data you want to add to the plot for later referencing.

A1. JSON Polygon Format Example

A2. GeoJSON Polygon Format Example

A3. GeoJSON Point Format Example (≤ 4ha)

ℹ️ Use areaHa to explicitly define the plot size (between 0.1 and 4 hectares). If omitted, the default of 4 hectares will be used. The areaHa represents the surface area of a circular plot centered on the given coordinates.

🆕 What's new: Supports application/geo+json for both request and response. This is ideal for GIS-based workflows.

Example Request:

Adding Custom Data to plots

You can also use the optional customData field on plots as shown above. This flexible structure allows users to store relevant information about the business the invitation is being sent to, provided it follows these rules:

  • Maximum of 10 keys.

  • Data must be of type string, number, or boolean. Arrays are not supported due to validation and storage constraints.

This data is only visible to the business that adds the data. i.e. anyone you share plots with cannot see it.

Use Case #2: Upload Multiple Plots (Batch Upload)

Use this to upload many plots at once using a GeoJSON FeatureCollection. Each Feature can contain a Polygon, MultiPolygon, or Point geometry (for plots ≤ 4ha).

There are two batch endpoints:

  • Option A — POST /plots/batch/geojson: all or nothing. If one feature is invalid, no plots are created.

  • Option B (recommended) — POST /v2/plots/batch: partial success. Valid features are created, and every rejected feature is reported with its reason and, for duplicates, the ID of the existing plot.

Option A: All-or-nothing upload

Endpoint: POST https://api.tradeaware.live-eo.com/plots/batch/geojson

Headers

Request Body Example

Response

  • On success: A 201 OK with a list of created plots.

  • On failure: A 400 Bad Request if any of the plots fail schema validation.

⚠️ Important: This endpoint does not support partial success — if one plot is invalid, the entire batch is rejected.

🆕 What's new: This endpoint replaces the deprecated POST /plots/batch. It requires valid GeoJSON and enforces stricter validation to ensure dataset consistency.

Response Example

A) With accept:application/geo+json header

B) With accept:application/json header

Option B: Upload with partial success (v2)

Use this endpoint when you want every valid plot created even if some features in your file fail, or when you re-send files that may contain plots you already uploaded. Each feature is checked and created on its own, and the response tells you what happened to each one.

Endpoint: POST https://api.tradeaware.live-eo.com/v2/plots/batch

Headers

Requests sent with another Content-Type are rejected with 400 Bad Request.

Request Body

The same GeoJSON FeatureCollection as in Option A, with 1 to 10,000 features per request. Each feature needs name, commodities and a geometry (Polygon, MultiPolygon, or Point for plots ≤ 4ha). The other plot properties, such as description, customData and areaHa, are optional.

Response (201)

The endpoint always responds with 201, also when every feature was rejected. Check status for the outcome:

  • SUCCESS: all features were created.

  • PARTIAL_FAILURE: some features were created, others were rejected.

  • FAILURE: no plots were created. The reason for each feature is still in failed.

  • index: position of the feature in your FeatureCollection, starting at 0.

  • created[].plot: the created plot, in the same format as the JSON response of POST /plots.

  • failed[].code: why the feature was rejected.

Code

Meaning

PLOT_ALREADY_EXISTS

A plot with exactly the same geometry and commodities already exists in your account. existingPlotId is the ID of that plot.

DUPLICATE_IN_REQUEST

The feature repeats an earlier feature in the same request. duplicateOfIndex points to that feature, and existingPlotId to the plot created from it.

INVALID_GEOMETRY

The geometry is invalid, self-intersecting or outside the allowed area range.

VALIDATION_FAILED

Another property is missing or invalid, for example name or commodities.

INTERNAL_ERROR

The plot could not be saved.

Duplicates and re-uploads

  • A duplicate means exactly the same geometry (the same coordinates) and the same commodities as a plot in your account. Overlapping or slightly different shapes are not duplicates, and deleted plots don't count.

  • Re-sending a file is safe: plots that already exist come back as PLOT_ALREADY_EXISTS with their IDs, and nothing is created twice.

  • Store created[].plot.id and existingPlotId against your own plot IDs. You can use them directly to request analyses (see Use Case #3b).

  • In rare cases, when two uploads of the same plot run at the same time, existingPlotId can be missing.

Use Case #3α: Request an Analysis

Once plots are uploaded, request analyses like deforestation detection to assess environmental compliance.

Endpoint: POST https://api.tradeaware.live-eo.com/plots/{plotId}/analyses

Required Parameters:

  • plotId: ID of the plot on which to perform the analysis.

  • name: A user-friendly name for reference.

  • type: Type of analysis to be performed, such as:

    • EUFOROBS: EU Global Map of Forest Cover.

    • PRECISION: Precision deforestation analysis powered by LiveEO.

    • OS: Multi-layer open-source deforestation analysis. Supersedes EUFOROBS — it includes all EUFOROBS data plus additional open-source layers. The layers included depend on the plot's commodity:

      • Timber plots: Global Forest Type 2020 (GFT2020)

      • All other commodities: Global Forest Cover 2020v3 (GFCv2020v3)

      • All commodities additionally receive the aggregated Tree Cover Loss 2020–2024 layer.

      • Results are returned per layer via the v2 endpoint (see Use Case #4).

  • metadata: This can be used to store any additional information that is relevant to the analysis. It is not used for any calculations, and is turned unchanged.

Example Request:

Response

Use Case #3b: Request Analyses in Bulk (PRECISION & EUFOROBS)

Queue analyses for many plots at once. Processing is asynchronous.

Endpoint POST https://api.tradeaware.live-eo.com/analyses/batch

Headers

Request Body

  • plotIds (required): 1–1000 plot IDs you can access.

  • type (required): "PRECISION", "EUFOROBS", or "OS".

Response (201) — summary

Note: If status is PARTIAL_FAILURE, some plots were queued successfully while others failed.

  • Check the errors object for each failed plotId.

  • You only need to retry the failed plots after correcting the issue.

Use Case #4: Get Analysis Results

Track the status of an analysis after submission and retrieve results when ready. You can either poll the API periodically or use webhooks to receive real-time updates — webhooks are strongly recommended for scalable workflows.

Retrieving OS Analysis Results (V2)

OS analyses return results per individual data layer. To retrieve them, use the v2 endpoint:

Endpoint: GET https://api.tradeaware.live-eo.com/v2/plots/{plotId}/analyses

Unlike the standard v1 response, each analysis object contains a results array — one entry per layer — instead of the aggregated deforestedArea, deforestedGeometry, and riskOfDeforestation fields.

Response Example

Note: The v1 endpoint (/plots/{plotId}/analyses) does not return OS analyses. Use v2 whenever you request or retrieve OS type results.

✅ Recommended: Get Analysis Results via Webhooks

Instead of manually polling the /analyses/{analysisId} endpoint to check for completion, you can now subscribe to webhooks and receive real-time notifications when an analysis is completed.

This is the recommended approach for scalable and efficient workflows, especially when monitoring a large number of plots.

📘 Read the full Webhooks Guide: TradeAware Webhooks Documentation

Note: Webhooks eliminate the need for polling and reduce load on your systems, making them ideal for high-volume or automated reporting workflows.

Optional: Polling via API (If Webhooks Not Used)

You can still use polling to check analysis status manually if webhooks are not configured.

Endpoint: GET https://api.tradeaware.live-eo.com/analyses/{analysisId}

Response Example

PreviousEndpoints enabled for programmatic access
NextConnect with your supply chain

Last updated