Upload and Analyzing Plots
This guide walks you through how to upload plots, request analyses, and track their status via the TradeAware Public API.
What’s Changed (June 2025)
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
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+jsonRequired 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
{
"commodities": ["soya"],
"name": "Plot A",
"geometry": {
"type": "Polygon",
"coordinates": [[[...], [...], [...], [...]]]
},
"description": "Test plot in region X"
}A2. GeoJSON Format Example
{
"type": "Feature",
"properties": {
"name": "Plot A",
"commodities": ["soya"],
"description": "Test plot in region X"
},
"geometry": {
"type": "Polygon",
"coordinates": [[[...], [...], [...], [...]]]
}
}🆕 What's new: Supports
application/geo+jsonfor both request and response. This is ideal for GIS-based workflows.
Example Request:
curl -X POST https://api.tradeaware.live-eo.com/plots -H "Authorization: Bearer <token>" \
-H 'accept: application/geo+json' \
-H 'content-type: application/geo+json' \
-d '{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [[[...], [...], [...], [...]]]
},
"properties": {
"commodities": ["soya"],
"name": "Plot A",
"description": "Test plot in region X",
"customData": {
"field": "value"
}
}'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.
Endpoint: POST https://api.tradeaware.live-eo.com/plots/batch/geojson
Headers
Authorization: Bearer <token>
Content-Type: application/geo+json
Accept: application/geo+jsonRequest Body Example
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"name": "Plot A",
"commodities": ["soya"]
},
"geometry": {
"type": "Polygon",
"coordinates": [[[102.0, 0.0], [103.0, 0.0], [103.0, 1.0], [102.0, 1.0], [102.0, 0.0]]]
}
},
{
"type": "Feature",
"properties": {
"name": "Plot B",
"commodities": ["oil palm"]
},
"geometry": {
"type": "Polygon",
"coordinates": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]
}
}
]
}Response
On success: A
201 OKwith a list of created plots.On failure: A
400 Bad Requestif 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
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "c6cddd2c-6f8a-46be-907e-c1d58bc18b6f",
"geometry": {
"type": "Polygon",
"coordinates": [[[...], [...], [...], [...]]]
},
"properties": {
"commodities": ["cocoa"],
"name": "geojson polygon 1",
"surfaceArea": 397.5,
"countryCode": "FR",
"filename": null,
"description": "description",
"customData": null
"updatedAt": "2025-06-13T13:20:05.456Z",
"createdAt": "2025-06-13T13:20:05.456Z"
}
},
{
"type": "Feature",
"id": "c6cddd2c-6f8a-46be-907e-c1d58bc18b6f",
"geometry": {
"type": "Polygon",
"coordinates": [[[...], [...], [...], [...]]]
},
"properties": {
"commodities": ["cocoa"],
"name": "geojson polygon 2",
"surfaceArea": 13.2,
"countryCode": "SN",
"filename": null,
"description": "description",
"customData": null
"updatedAt": "2025-06-13T13:20:05.456Z",
"createdAt": "2025-06-13T13:20:05.456Z"
}
}
]
}B) With accept:application/json header
[
{
"id": "c6cddd2c-6f8a-46be-907e-c1d58bc18b6f",
"commodities": ["cocoa"],
"geometry": {
"type": "Polygon",
"coordinates": [[[...], [...], [...], [...]]]
},
"name": "geojson polygon 1",
"surfaceArea": 397.5,
"countryCode": "FR",
"filename": null,
"description": "description",
"customData": null
"updatedAt": "2025-06-13T13:20:05.456Z",
"createdAt": "2025-06-13T13:20:05.456Z"
},
{
"id": "c6cddd2c-6f8a-46be-907e-c1d58bc18b6f",
"commodities": ["cocoa"],
"geometry": {
"type": "Polygon",
"coordinates": [[[...], [...], [...], [...]]]
},
"name": "geojson polygon 2",
"surfaceArea": 13.2,
"countryCode": "SN",
"filename": null,
"description": "description",
"customData": null
"updatedAt": "2025-06-13T13:20:05.456Z",
"createdAt": "2025-06-13T13:20:05.456Z"
}
]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.
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:
curl -X POST https://api.tradeaware.live-eo.com/plots/{plotId}/analyses -H "Authorization: Bearer <token>" \
-H 'content-type: application/json' \
-d '{
"name": "Deforestation Analysis 2024",
"type": "PRECISION",
"metadata": {"notes": "High-priority area"}
}'Response
{
"analysisId": "abc123",
"plotId": "xyz456",
"status": "PENDING"
}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.
✅ 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
{
"plotId": "xyz456",
"status": "SUCCEEDED",
"deforestedArea": 12155.5,
"deforestedGeometry": { ... },
"riskOfDeforestation": 0.81,
"confidenceScore": 0.92,
"processingNotes": "Model confidence high. QA passed."
}Last updated