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

{
  "commodities": ["soya"],
  "name": "Plot A",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[...], [...], [...], [...]]]
  },
  "description": "Test plot in region X"
}

A2. GeoJSON Polygon Format Example

{
  "type": "Feature",
  "properties": {
    "name": "Plot A",
    "commodities": ["soya"],
    "description": "Test plot in region X"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[...], [...], [...], [...]]]
  }
}

A3. GeoJSON Point Format Example (≤ 4ha)

{
  "type": "Feature",
  "properties": {
    "name": "Smallholder Plot",
    "commodities": ["cocoa"],
    "description": "Point-based plot for smallholder",
    "areaHa": 2.5
  },
  "geometry": {
    "type": "Point",
    "coordinates": [30.7255, 2.1896]
  }
}

ℹ️ 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:

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. Each Feature can contain a Polygon, MultiPolygon, or Point geometry (for plots ≤ 4ha).

---

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

Headers

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

Request 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": "Point Plot",
        "commodities": ["coffee"],
        "areaHa": 3.5
      },
      "geometry": {
        "type": "Point",
        "coordinates": [34.5689, 1.2345]
      }
    }
  ]
}

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

{
  "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 #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

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

Request Body

{
  "plotIds": ["<plot-id-1>", "<plot-id-2>", "..."],
  "type": "PRECISION"   // or "EUFOROBS"
}

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

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

Response (201) — summary

{
  "status": "SUCCESS | PARTIAL_FAILURE | FAILURE",
  "errors": { "<plot-id>": "reason" },
  "processed": {
    "<plot-id>": "{\"id\":\"<analysis-id>\",\"status\":\"pending\",\"type\":\"PRECISION\"}"
  }
}

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.

✅ 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."
}