Plots

List all plots.

Lists all plots of your business.

get

/plots

Authorizations

Query parameters

pagenumber

Page number to retrieve.If you provide invalid value the default page number will applied <p> <b>Example: </b> 1 </p> <p> <b>Default Value: </b> 1 </p>

limitnumber

Number of records per page. <p> <b>Example: </b> 20 </p> <p> <b>Default Value: </b> 100 </p> <p> <b>Max Value: </b> 500 </p>

  If provided value is greater than max value, max value will be applied.

filter.commoditiesstring[]

Filter by commodities query param. <p> <b>Format: </b> filter.commodities={$not}:OPERATION:VALUE </p> <p> <b>Example: </b> filter.commodities=$not:$like:John Doe&filter.commodities=like:John </p> <h4>Available Operations</h4><ul><li>$contains</li></ul>

sortBystring · enum[]

Parameter to sort by. <p>To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting</p> <p> <b>Format: </b> fieldName:DIRECTION </p> <p> <b>Example: </b> sortBy=id:DESC&sortBy=createdAt:ASC </p> <p> <b>Default Value: </b> createdAt:DESC </p> <h4>Available Fields</h4><ul><li>createdAt</li></ul>

selectstring

List of fields to select. <p> <b>Example: </b> </p> <p> <b>Default Value: </b> By default all fields returns. If you want to select only some fields, provide them in query param </p>

includesany

A comma-separated list of relations to be included in the response. Possible relations are: mostRecentAnalysis, suppliers, mostRecentAnalysesByType. Deprecation: 'mostRecentAnalysis' is deprecated. Please use 'mostRecentAnalysesByType' as the response data will in particular include the data from 'mostRecentAnalysis'.

Example: mostRecentAnalysesByType

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.tradeaware.live-eo.com/plots' \
  --header 'Authorization: Bearer JWT'

200

401

403

501

200

[
  {
    "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
    "createdAt": "2023‐07‐26T15:03:48Z",
    "updatedAt": "2023‐07‐28T09:13:37Z",
    "suppliers": [
      "[Circular Reference]"
    ],
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            100,
            0
          ],
          [
            101,
            0
          ],
          [
            101,
            1
          ],
          [
            100,
            1
          ],
          [
            100,
            0
          ]
        ]
      ]
    },
    "commodities": [
      "oil palm",
      "rubber"
    ],
    "name": "text",
    "surfaceArea": 1,
    "countryCode": "text",
    "mostRecentAnalysis": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "status": "started",
      "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "analysedAt": "2023-07-28T09:13:37Z",
      "version": "open-source-1.0.0",
      "deforestedArea": 123.45,
      "deforestedGeometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              13,
              52.5
            ],
            [
              13.5,
              52.5
            ],
            [
              13.5,
              52
            ],
            [
              13,
              52
            ],
            [
              13,
              52.5
            ]
          ]
        ]
      },
      "riskOfDeforestation": 0.3,
      "type": "EUFOROBS"
    },
    "mostRecentAnalysesByType": {
      "EUFOROBS": {
        "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
        "createdAt": "2023-07-26T15:03:48Z",
        "updatedAt": "2023-07-28T09:13:37Z",
        "status": "started",
        "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
        "analysedAt": "2023-07-28T09:13:37Z",
        "version": "open-source-1.0.0",
        "deforestedArea": 123.45,
        "deforestedGeometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                13,
                52.5
              ],
              [
                13.5,
                52.5
              ],
              [
                13.5,
                52
              ],
              [
                13,
                52
              ],
              [
                13,
                52.5
              ]
            ]
          ]
        },
        "riskOfDeforestation": 0.3,
        "type": "EUFOROBS"
      },
      "PRECISION": {
        "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
        "createdAt": "2023-07-26T15:03:48Z",
        "updatedAt": "2023-07-28T09:13:37Z",
        "status": "started",
        "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
        "analysedAt": "2023-07-28T09:13:37Z",
        "version": "open-source-1.0.0",
        "deforestedArea": 123.45,
        "deforestedGeometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                13,
                52.5
              ],
              [
                13.5,
                52.5
              ],
              [
                13.5,
                52
              ],
              [
                13,
                52
              ],
              [
                13,
                52.5
              ]
            ]
          ]
        },
        "riskOfDeforestation": 0.3,
        "type": "EUFOROBS"
      }
    }
  }
]

A list of all plots

Create a plot.

Create a plot owned by your business.

post

/plots

Authorizations

Body

commoditiesstring · enum[]required

What crops (among the relevant commodities) are grown on this field (currently).

Example: ["oil palm","rubber"]

namestringrequired

Free text name of the plot. Useful for easily finding and identifying the plot as an enduser.

descriptionstring

Short description to find and identify plots as owners.

geometryall ofrequired

The geometry of the plot with the polygon. Currently supported: Polygon geometry as defined in https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Example: {"type":"Polygon","coordinates":[[[100,0],[101,0],[101,1],[100,1],[100,0]]]}

countryCodestringDeprecated

Deprecated. This will be automatically populated by the system. The country code (ISO 31661Alpha2 expected).

isActiveboolean · default: true

Is this plot active in the system

filenamestring

Filename of the file where the plot is defined

customDataobject

A customizable metadata field for storing additional information related to a plot in TradeAware. This field allows customers to associate their own identifiers or data with TradeAware's system.

  The `customData` field is returned unchanged and is visible only to the owners of the plot.

  Constraints:
    - Up to 10 keys per object
    - Key length: Maximum 255 characters
    - String value length: Maximum 255 characters
    - Values must be of type: string, number, or boolean
    - Nested objects are not allowed
    - Keys cannot contain: '__proto__', 'constructor', or 'prototype'

Example: {"key1":"someValue","key2":true,"key3":1234}

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.tradeaware.live-eo.com/plots' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "commodities": [
      "oil palm",
      "rubber"
    ],
    "name": "text",
    "description": "text",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            100,
            0
          ],
          [
            101,
            0
          ],
          [
            101,
            1
          ],
          [
            100,
            1
          ],
          [
            100,
            0
          ]
        ]
      ]
    },
    "countryCode": "text",
    "isActive": true,
    "filename": "text",
    "customData": {
      "key1": "someValue",
      "key2": true,
      "key3": 1234
    }
  }'

201

400

401

403

201

{
  "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
  "createdAt": "2023‐07‐26T15:03:48Z",
  "updatedAt": "2023‐07‐28T09:13:37Z",
  "suppliers": [
    {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "email": "[e-mail]",
      "name": "Example Inc.",
      "username": "John Doe",
      "addressStreet": "Salawati 143",
      "addressZip": "98451",
      "addressPostcode": "12345",
      "addressArea": "Brandenburg",
      "addressCity": "West Papua",
      "addressCountryCode": "ID",
      "addressCountry": "Indonesia",
      "addressLine1": "Salawati 123",
      "addressLine2": "3rd floor",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "initialLocale": "id-ID",
      "units": "metric",
      "plots": "[Circular Reference]",
      "newlyCreated": "true",
      "members": "[Circular Reference]",
      "connectionsAsSource": "[Circular Reference]",
      "connectionsAsTarget": "[Circular Reference]",
      "businessInvitations": "[Circular Reference]",
      "contactPerson": "[Circular Reference]",
      "machineToMachineClientId": "1234567890asdfghjk",
      "eori": "text",
      "vat": "text"
    }
  ],
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          100,
          0
        ],
        [
          101,
          0
        ],
        [
          101,
          1
        ],
        [
          100,
          1
        ],
        [
          100,
          0
        ]
      ]
    ]
  },
  "commodities": [
    "oil palm",
    "rubber"
  ],
  "name": "text",
  "surfaceArea": 1,
  "countryCode": "text",
  "mostRecentAnalysis": {
    "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
    "createdAt": "2023-07-26T15:03:48Z",
    "updatedAt": "2023-07-28T09:13:37Z",
    "status": "started",
    "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
    "analysedAt": "2023-07-28T09:13:37Z",
    "version": "open-source-1.0.0",
    "deforestedArea": 123.45,
    "deforestedGeometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            13,
            52.5
          ],
          [
            13.5,
            52.5
          ],
          [
            13.5,
            52
          ],
          [
            13,
            52
          ],
          [
            13,
            52.5
          ]
        ]
      ]
    },
    "riskOfDeforestation": 0.3,
    "type": "EUFOROBS",
    "metadata": {
      "some": "metadata"
    },
    "name": "text"
  },
  "mostRecentAnalysesByType": {
    "EUFOROBS": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "status": "started",
      "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "analysedAt": "2023-07-28T09:13:37Z",
      "version": "open-source-1.0.0",
      "deforestedArea": 123.45,
      "deforestedGeometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              13,
              52.5
            ],
            [
              13.5,
              52.5
            ],
            [
              13.5,
              52
            ],
            [
              13,
              52
            ],
            [
              13,
              52.5
            ]
          ]
        ]
      },
      "riskOfDeforestation": 0.3,
      "type": "EUFOROBS",
      "metadata": {
        "some": "metadata"
      },
      "name": "text"
    },
    "PRECISION": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "status": "started",
      "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "analysedAt": "2023-07-28T09:13:37Z",
      "version": "open-source-1.0.0",
      "deforestedArea": 123.45,
      "deforestedGeometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              13,
              52.5
            ],
            [
              13.5,
              52.5
            ],
            [
              13.5,
              52
            ],
            [
              13,
              52
            ],
            [
              13,
              52.5
            ]
          ]
        ]
      },
      "riskOfDeforestation": 0.3,
      "type": "EUFOROBS",
      "metadata": {
        "some": "metadata"
      },
      "name": "text"
    }
  },
  "filename": {},
  "description": "text",
  "ownerId": "text",
  "customData": {
    "key1": "someValue",
    "key2": true,
    "key3": 1234
  }
}

Retrieve a plot.

Retrieve the specified plot.

get

/plots/{id}

Authorizations

Path parameters

idstringrequired

Query parameters

includesany

A comma-separated list of relations to be included in the response. Possible relations are: mostRecentAnalysis.

Example: mostRecentAnalysis

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.tradeaware.live-eo.com/plots/{id}' \
  --header 'Authorization: Bearer JWT'

200

401

403

404

200

{
  "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
  "createdAt": "2023‐07‐26T15:03:48Z",
  "updatedAt": "2023‐07‐28T09:13:37Z",
  "suppliers": [
    "[Circular Reference]"
  ],
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          100,
          0
        ],
        [
          101,
          0
        ],
        [
          101,
          1
        ],
        [
          100,
          1
        ],
        [
          100,
          0
        ]
      ]
    ]
  },
  "commodities": [
    "oil palm",
    "rubber"
  ],
  "name": "text",
  "surfaceArea": 1,
  "countryCode": "text",
  "mostRecentAnalysis": {
    "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
    "createdAt": "2023-07-26T15:03:48Z",
    "updatedAt": "2023-07-28T09:13:37Z",
    "status": "started",
    "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
    "analysedAt": "2023-07-28T09:13:37Z",
    "version": "open-source-1.0.0",
    "deforestedArea": 123.45,
    "deforestedGeometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            13,
            52.5
          ],
          [
            13.5,
            52.5
          ],
          [
            13.5,
            52
          ],
          [
            13,
            52
          ],
          [
            13,
            52.5
          ]
        ]
      ]
    },
    "riskOfDeforestation": 0.3,
    "type": "EUFOROBS"
  },
  "mostRecentAnalysesByType": {
    "EUFOROBS": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "status": "started",
      "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "analysedAt": "2023-07-28T09:13:37Z",
      "version": "open-source-1.0.0",
      "deforestedArea": 123.45,
      "deforestedGeometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              13,
              52.5
            ],
            [
              13.5,
              52.5
            ],
            [
              13.5,
              52
            ],
            [
              13,
              52
            ],
            [
              13,
              52.5
            ]
          ]
        ]
      },
      "riskOfDeforestation": 0.3,
      "type": "EUFOROBS"
    },
    "PRECISION": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "status": "started",
      "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "analysedAt": "2023-07-28T09:13:37Z",
      "version": "open-source-1.0.0",
      "deforestedArea": 123.45,
      "deforestedGeometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              13,
              52.5
            ],
            [
              13.5,
              52.5
            ],
            [
              13.5,
              52
            ],
            [
              13,
              52
            ],
            [
              13,
              52.5
            ]
          ]
        ]
      },
      "riskOfDeforestation": 0.3,
      "type": "EUFOROBS"
    }
  }
}

Update a plot.

Update the properties of the specified plot. Handles updates partially, i.e. properties missing in the request body will not be changed.

patch

/plots/{id}

Authorizations

Path parameters

idstringrequired

Body

commoditiesstring · enum[]

What crops (among the relevant commodities) are grown on this field (currently).

Example: ["oil palm","rubber"]

namestring

Free text name of the plot. Useful for easily finding and identifying the plot as an enduser.

descriptionstring

Short description to find and identify plots as owners.

geometryall of

The geometry of the plot with the polygon. Currently supported: Polygon geometry as defined in https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Example: {"type":"Polygon","coordinates":[[[100,0],[101,0],[101,1],[100,1],[100,0]]]}

countryCodestringDeprecated

Deprecated. This will be automatically populated by the system. The country code (ISO 31661Alpha2 expected).

isActiveboolean · default: true

Is this plot active in the system

filenamestring

Filename of the file where the plot is defined

customDataobject

A customizable metadata field for storing additional information related to a plot in TradeAware. This field allows customers to associate their own identifiers or data with TradeAware's system.

  The `customData` field is returned unchanged and is visible only to the owners of the plot.

  Constraints:
    - Up to 10 keys per object
    - Key length: Maximum 255 characters
    - String value length: Maximum 255 characters
    - Values must be of type: string, number, or boolean
    - Nested objects are not allowed
    - Keys cannot contain: '__proto__', 'constructor', or 'prototype'

Example: {"key1":"someValue","key2":true,"key3":1234}

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://api.tradeaware.live-eo.com/plots/{id}' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "commodities": [
      "oil palm",
      "rubber"
    ],
    "name": "text",
    "description": "text",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            100,
            0
          ],
          [
            101,
            0
          ],
          [
            101,
            1
          ],
          [
            100,
            1
          ],
          [
            100,
            0
          ]
        ]
      ]
    },
    "countryCode": "text",
    "isActive": true,
    "filename": "text",
    "customData": {
      "key1": "someValue",
      "key2": true,
      "key3": 1234
    }
  }'

200

401

403

404

200

{
  "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
  "createdAt": "2023‐07‐26T15:03:48Z",
  "updatedAt": "2023‐07‐28T09:13:37Z",
  "suppliers": [
    {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "email": "[e-mail]",
      "name": "Example Inc.",
      "username": "John Doe",
      "addressStreet": "Salawati 143",
      "addressZip": "98451",
      "addressPostcode": "12345",
      "addressArea": "Brandenburg",
      "addressCity": "West Papua",
      "addressCountryCode": "ID",
      "addressCountry": "Indonesia",
      "addressLine1": "Salawati 123",
      "addressLine2": "3rd floor",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "initialLocale": "id-ID",
      "units": "metric",
      "plots": "[Circular Reference]",
      "newlyCreated": "true",
      "members": "[Circular Reference]",
      "connectionsAsSource": "[Circular Reference]",
      "connectionsAsTarget": "[Circular Reference]",
      "businessInvitations": "[Circular Reference]",
      "contactPerson": "[Circular Reference]",
      "machineToMachineClientId": "1234567890asdfghjk",
      "eori": "text",
      "vat": "text"
    }
  ],
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          100,
          0
        ],
        [
          101,
          0
        ],
        [
          101,
          1
        ],
        [
          100,
          1
        ],
        [
          100,
          0
        ]
      ]
    ]
  },
  "commodities": [
    "oil palm",
    "rubber"
  ],
  "name": "text",
  "surfaceArea": 1,
  "countryCode": "text",
  "mostRecentAnalysis": {
    "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
    "createdAt": "2023-07-26T15:03:48Z",
    "updatedAt": "2023-07-28T09:13:37Z",
    "status": "started",
    "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
    "analysedAt": "2023-07-28T09:13:37Z",
    "version": "open-source-1.0.0",
    "deforestedArea": 123.45,
    "deforestedGeometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            13,
            52.5
          ],
          [
            13.5,
            52.5
          ],
          [
            13.5,
            52
          ],
          [
            13,
            52
          ],
          [
            13,
            52.5
          ]
        ]
      ]
    },
    "riskOfDeforestation": 0.3,
    "type": "EUFOROBS",
    "metadata": {
      "some": "metadata"
    },
    "name": "text"
  },
  "mostRecentAnalysesByType": {
    "EUFOROBS": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "status": "started",
      "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "analysedAt": "2023-07-28T09:13:37Z",
      "version": "open-source-1.0.0",
      "deforestedArea": 123.45,
      "deforestedGeometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              13,
              52.5
            ],
            [
              13.5,
              52.5
            ],
            [
              13.5,
              52
            ],
            [
              13,
              52
            ],
            [
              13,
              52.5
            ]
          ]
        ]
      },
      "riskOfDeforestation": 0.3,
      "type": "EUFOROBS",
      "metadata": {
        "some": "metadata"
      },
      "name": "text"
    },
    "PRECISION": {
      "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "createdAt": "2023-07-26T15:03:48Z",
      "updatedAt": "2023-07-28T09:13:37Z",
      "status": "started",
      "plotId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
      "analysedAt": "2023-07-28T09:13:37Z",
      "version": "open-source-1.0.0",
      "deforestedArea": 123.45,
      "deforestedGeometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              13,
              52.5
            ],
            [
              13.5,
              52.5
            ],
            [
              13.5,
              52
            ],
            [
              13,
              52
            ],
            [
              13,
              52.5
            ]
          ]
        ]
      },
      "riskOfDeforestation": 0.3,
      "type": "EUFOROBS",
      "metadata": {
        "some": "metadata"
      },
      "name": "text"
    }
  },
  "filename": {},
  "description": "text",
  "ownerId": "text",
  "customData": {
    "key1": "someValue",
    "key2": true,
    "key3": 1234
  }
}

Delete a plot.

Deletes the specified plot. Uses soft-deletion instead of regular deletion to ensure auditability. There is currently no way to undo the soft-deletion via the API.

delete

/plots/{id}

Authorizations

Path parameters

idstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.tradeaware.live-eo.com/plots/{id}' \
  --header 'Authorization: Bearer JWT'

204

401

403

404

500

204

No body