Plots

List all plots.

get

Lists all plots of your business.

Authorizations

Query parameters

pagenumberoptional

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

limitnumberoptional

Number of records per page. Example: 20 Default Value: 100 Max Value: 500

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

filter.commoditiesstring[]optional

Filter by commodities query param. Format: filter.commodities={$not}:OPERATION:VALUE Example: filter.commodities=$not:$like:John Doe&filter.commodities=like:John Available Operations$contains

sortBystring · enum[]optional

Parameter to sort by. To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting Format: fieldName:DIRECTION Example: sortBy=id:DESC&sortBy=createdAt:ASC Default Value: createdAt:DESC Available FieldscreatedAt

selectstringoptional

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

includesanyoptional

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.

post

Create a plot owned by your business.

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.

descriptionstringoptional

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]]]}

countryCodestringoptionalDeprecated

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

isActiveboolean · default: trueoptional

Is this plot active in the system

filenamestringoptional

Filename of the file where the plot is defined

customDataobjectoptional

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
    }
  }'

application/json

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.

get

Retrieve the specified plot.

Authorizations

Path parameters

idstringrequired

Query parameters

includesanyoptional

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.

patch

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

Authorizations

Path parameters

idstringrequired

Body

commoditiesstring · enum[]optional

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

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

namestringoptional

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

descriptionstringoptional

Short description to find and identify plots as owners.

geometryall ofoptional

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]]]}

countryCodestringoptionalDeprecated

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

isActiveboolean · default: trueoptional

Is this plot active in the system

filenamestringoptional

Filename of the file where the plot is defined

customDataobjectoptional

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
    }
  }'

application/json

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.

delete

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.

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