TradeAware
  • Welcome to TradeAware User Guide
    • Getting Started
  • Using the TradeAware Web App
    • Upload and Analyzing Plots
    • Connect with your supply chain
    • Provide and Review Documents
    • Assess risk in your supply chain
    • Manage your transactions
    • Plot Upload and Analysis Trouble Shooting
    • How-to videos
  • Using the TradeAware API
    • API Access and Business Account Registration
    • Webhooks Guide
    • Authentication
      • Rotate client secret
      • Endpoints enabled for programmatic access
    • Upload and Analyzing Plots
    • Connect with your supply chain
    • Assess risk in your supply chain
    • Manage your transactions
    • API reference
      • Auth
      • Plots
        • Analyses of a specific Plot
        • Batch
      • Analyses
      • Attachments
      • Business invitations
        • Create a business invitation
        • Create multiple business invitations
        • Update a business invitation
        • List all received invitations
        • List all sent invitations
      • Business connections
      • Transactions
        • Create a Transaction
        • Retrieve Transactions
          • Get a transaction by id
          • List all transactions
        • Modify an existing Transaction
          • Update a Transaction
          • Add a Transaction Component
          • Update a Transaction Component
          • Delete a Transaction Component
        • Delete a Transaction
        • Submit a Transaction
        • Retrieve DDS Data
      • Risk Assessments
        • Supplier Risk Assessments
          • Create a Supplier Risk Assessment
          • Update a Supplier Risk Assessment
          • Retrieve Supplier Risk Assessments
            • Get a supplier risk assessment by id
            • Get all supplier risk assessments
          • Retrieve the history
        • Plot Risk Assessments
          • Create a Plot Risk Assessment
          • Update a Plot Risk Assessment
          • Retrieve Plot Risk Assessments
            • Get a plot risk assessment by id
            • Get all plot risk assessments
          • Retrieve the history
      • Survey responses
      • Health
      • Version
      • Specification
  • Additional Resources
    • FAQs
    • Contact Support
    • Terms and Conditions
Powered by GitBook
On this page
  • What’s Changed (June 2025)
  • Use Case #1: Upload Geolocation Information
  • Use Case #2: Upload Multiple Plots (Batch Upload)
  • Use Case #3: Request an Analysis
  • Use Case #4: Get Analysis Results
  1. Using the TradeAware API

Upload and Analyzing Plots

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

PreviousEndpoints enabled for programmatic accessNextConnect with your supply chain

Last updated 15 hours ago

What’s Changed (June 2025)

Area
Change

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:

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 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+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.


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": "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 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.


Use Case #3: Request an Analysis

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:

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.

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.

Response Example

{
  "plotId": "xyz456",
  "status": "SUCCEEDED",
  "deforestedArea": 12155.5,
  "deforestedGeometry": { ... },
  "riskOfDeforestation": 0.81,
  "confidenceScore": 0.92,
  "processingNotes": "Model confidence high. QA passed."
}

Endpoint:

Endpoint: POST

📘 Read the full Webhooks Guide:

Endpoint: GET

POST https://api.tradeaware.live-eo.com/plots
POST https://api.tradeaware.live-eo.com/plots/batch/geojson
https://api.tradeaware.live-eo.com/plots/{plotId}/analyses
TradeAware Webhooks Documentation
https://api.tradeaware.live-eo.com/analyses/{analysisId}