Upload and Analyzing Plots
This guide walks you through how to upload plots, request analyses, and track their status via the TradeAware Public API.
Last updated
This guide walks you through how to upload plots, request analyses, and track their status via the TradeAware Public API.
Last updated
Request format
You can now use GeoJSON via Content-Type: application/geo+json
Batch upload
The old /plots/batch
endpoint is deprecated. Use /plots/batch/geojson
instead
Response format
Set Accept: application/geo+json
to receive responses in GeoJSON format
Validation
Schema is validated based on Content-Type
(JSON vs GeoJSON)
Batch failures
GeoJSON batch upload is atomic — if one plot fails, none are uploaded
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.
Endpoint:
Headers
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 Polygon format.
description
: Additional plot details for easy referencing.
Optional Fields:
customData
: custom data you want to add to the plot for later referencing.
A1. JSON Format Example
A2. GeoJSON Format Example
🆕 What's new: Supports
application/geo+json
for both request and response. This is ideal for GIS-based workflows.
Example Request:
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 this to upload many plots at once using a GeoJSON FeatureCollection.
Headers
Request Body Example
Response
On success: A 200 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.
Once plots are uploaded, request analyses like deforestation detection to assess environmental compliance.
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.
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
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.
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.
Note: Webhooks eliminate the need for polling and reduce load on your systems, making them ideal for high-volume or automated reporting workflows.
You can still use polling to check analysis status manually if webhooks are not configured.
Response Example
Endpoint:
Endpoint: POST
📘 Read the full Webhooks Guide:
Endpoint: GET