Upload and Analyzing Plots

This guide provides a step-by-step overview of using the API for key use cases, such as uploading geolocation information, requesting analysis, and tracking analysis status.

Use Case #1: Upload Geolocation Information

Endpoint: POST /plots

This endpoint allows you to upload data for individual plots, specifying essential attributes and location details for monitoring and analysis.

Request: POST https://api.tradeaware.live-eo.com/plots

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.

Example Request:

curl -X POST https://api.tradeaware.live-eo.com/plots -H "Authorization: Bearer <token>" \
-d '{
  "commodities": ["soy"],
  "name": "Plot A",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[...], [...], [...], [...]]]
  },
  "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.

Endpoint: POST /plots/batch

For batch uploads, this endpoint enables multiple plot uploads at once, streamlining the process for large datasets.

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

Required Fields:

• commodities: Crops grown on each plot.

• filename: Name of the file containing the plot data.

• geometry: GeoJSON Polygon data for each plot location.

Example Request:

curl -X POST https://api.tradeaware.live-eo.com/plots/batch -H "Authorization: Bearer <token>" \
-d '{
  "commodities": [
    "soya",
    "cocoa"
  ],
  "geometries": {
    "plotname1": {
        "coordinates": [...]
        "type": "Polygon"
      },
    "plotname2": {
        "coordinates": [...]
        "type": "Polygon"
      }
  },
  "filename": "myfile"
}'

Use Case #2: Request an Analysis

Once plot data is available, you can request a range of analyses, including deforestation monitoring, on specific plots.

Endpoint: POST /plots/{plotId}/analyses

Request: 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:

bashCopy codecurl -X POST https://api.tradeaware.live-eo.com/plots/{plotId}/analyses -H "Authorization: Bearer <token>" \
-d '{
  "name": "Deforestation Analysis 2024",
  "type": "PRECISION",
  "metadata": {"notes": "High-priority area"}
}'

Response:

• analysisId: Unique identifier for the analysis.

• plotId: ID of the plot the analysis is associated with.

• status: Current status of the analysis (e.g., not started, started, succeeded, failed).

Use Case #3: Check Analysis Status (Polling Mechanism)

After initiating an analysis, you can track its status to know when the results are ready.

Endpoint: GET /analyses/{analysisId}

Request: GET https://api.tradeaware.live-eo.com/analyses/{analysisId}

Required Parameter:

• analysisId: Unique identifier of the analysis to retrieve its status and results.

Example Request:

bashCopy codecurl -X GET https://api.tradeaware.live-eo.com/analyses/{analysisId} -H "Authorization: Bearer <token>"

Response Fields:

• plotId: ID of the plot on which this analysis was performed.

• status: Analysis pipeline status (PENDING, RUNNING, SUCCEEDED, FAILED).

• deforestedArea: Total area deforested (in square meters).

• deforestedGeometry: GeoJSON Polygon indicating the exact area deforested.

• riskOfDeforestation: A score between 0.0 (no risk) and 1.0 (certain deforestation).

*more fields are included in the response

Polling Frequency

The PRECISION analysis is scheduled to run daily at 12:00 PM UTC and typically takes about one hour to complete. If the model outcome does not meet our baseline accuracy standards, we will conduct quality control checks on the plots, which may extend the analysis duration.

To optimize your experience, we recommend setting your polling frequency to once per hour. This allows you to receive timely updates on the status of your analyses while we ensure that the data provided meets our rigorous quality standards.