# Upload and Analyzing Plots

**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`](/tradeaware/using-the-tradeaware-api/api-reference/plots.md)

**Headers**

```http
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**

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

**A2. GeoJSON Polygon Format Example**

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

>

**A3. GeoJSON Point Format Example (≤ 4ha)**

```json
{
  "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`](#endpoint-post-plots-batch)

**Headers**

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

**Request Body Example**

```json
{
 {
  "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

<pre><code><strong>{
</strong>  "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"
      }
    }
  ]
}
</code></pre>

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`](#endpoint-post-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**:

```json
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**

```json
{
  "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**

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

* `plotIds` (required): 1–1000 plot IDs you can access.
* `type` (required): `"PRECISION"`, `"EUFOROBS"`, or `"OS"`.

**Response (201) — summary**

```json
{
  "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.

#### 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**

```json
[
  {
    "id": "abc123",
    "plotId": "xyz456",
    "status": "SUCCEEDED",
    "type": "OS",
    "analysedAt": "2025-10-01T10:00:00.000Z",
    "results": [
      {
        "id": "res001",
        "layerName": "Global Forest Cover 2020v3",
        "layerClass": "Forest cover, 2020",
        "layerVersion": "v3",
        "overlapAreaSqm": 45230.5,
        "overlapPercentage": 0.74,
        "geometry": { "type": "Polygon", "coordinates": [[...]] }
      },
      {
        "id": "res002",
        "layerName": "Tree Cover Loss 2020-2024",
        "layerClass": "Tree cover loss, 2020-2024",
        "layerVersion": "2024",
        "overlapAreaSqm": 3120.0,
        "overlapPercentage": 0.05,
        "geometry": { "type": "Polygon", "coordinates": [[...]] }
      }
    ]
  }
]
```

> **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](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/webhooks-guide)

> **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}`](#endpoint-post-plots-plotid-analyses)

**Response Example**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "plotId": "xyz456",
  "status": "SUCCEEDED",
  "deforestedArea": 12155.5,
  "deforestedGeometry": { ... },
  "riskOfDeforestation": 0.81,
  "confidenceScore": 0.92,
  "processingNotes": "Model confidence high. QA passed."
}
</code></pre>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/upload-and-analyzing-plots.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.