Batch

Bulk-create plots in GeoJSON format.

post

Create multiple plots from a GeoJSON FeatureCollection.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

acceptstring · enumOptional

Specify the response format. Defaults to application/json.

Possible values:

Body

application/geo+json

typestringRequired

The type of the geojson object. Always 'FeatureCollection'

Example: FeatureCollection

Responses

201

All created plots

application/jsonapplication/geo+json

idstringRequired

id of this entity

Example: 02c36247-1aad-41ba-aa49-f114ca4c263f

createdAtstringRequired

ISO 8601

Example: 2023-07-26T15:03:48Z

updatedAtstringRequired

ISO 8601

Example: 2023-07-28T09:13:37Z

geometryone ofRequired

The geometry of the plot.

or

namestringRequired

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

surfaceAreanumberRequired

Surface area in square meters

countryCodestringRequired

ISO 3166-1 alpha-2 country code of where the plot is located

riskAssessmentStatusstring · enumOptional

The risk assessment status of this plot set by your business

Possible values:

riskLevelstring · enum · nullableOptional

The risk level of deforestation in this plot. IMPORTANT: only set when 'riskLevel' is provided in 'includes'. If no analysis on this plot is available yet, this property may be null.

Possible values:

filenameobject · nullableOptional

Filename of the plot. Useful to know where is the Plot coming from on batch create.

descriptionstring · nullableOptional

Free text descrption of the plot. Useful for to keep human friendly Plot names.

ownerIdstringOptional

The id of the owning business. May be undefined for supplier masking.

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}

401Error

403Error

post

/plots/batch/geojson

HTTPcURLJavaScriptPython

POST /plots/batch/geojson HTTP/1.1
Host: api.tradeaware.live-eo.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/geo+json
Accept: */*
Content-Length: 301

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          100,
          0
        ]
      },
      "properties": {
        "commodities": [
          "oil palm",
          "rubber"
        ],
        "name": "text",
        "description": "text",
        "isActive": true,
        "filename": "text",
        "customData": {
          "key1": "someValue",
          "key2": true,
          "key3": 1234
        },
        "areaHa": 0.5
      }
    }
  ]
}

[
  {
    "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": "[email protected]",
        "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": [
          {
            "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
                  ],
                  [
                    100.01,
                    0
                  ],
                  [
                    100.01,
                    0.01
                  ],
                  [
                    100,
                    0.01
                  ],
                  [
                    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": "PENDING",
              "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": "OS",
              "customData": {
                "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": "PENDING",
                "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": "OS",
                "customData": {
                  "some": "metadata"
                },
                "name": "text"
              },
              "PRECISION": {
                "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
                "createdAt": "2023-07-26T15:03:48Z",
                "updatedAt": "2023-07-28T09:13:37Z",
                "status": "PENDING",
                "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": "OS",
                "customData": {
                  "some": "metadata"
                },
                "name": "text"
              }
            },
            "riskAssessmentStatus": "NEW",
            "riskLevel": "none",
            "filename": {},
            "description": "text",
            "ownerId": "text",
            "customData": {
              "key1": "someValue",
              "key2": true,
              "key3": 1234
            }
          }
        ],
        "newlyCreated": "true",
        "members": [
          {
            "auth0UserId": "auth0|41ba-aa49-f114ca4c263f",
            "business": "[Circular Reference]",
            "businessId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
            "firstName": "Paul",
            "lastName": "Smith",
            "locale": "id-ID",
            "createdAt": "2023-07-26T15:03:48Z",
            "updatedAt": "2023-07-28T09:13:37Z",
            "completed": "false",
            "businessInvitations": "[Circular Reference]",
            "userInvitations": "[Circular Reference]",
            "email": "[email protected]",
            "consentedAt": "2023-07-28T09:13:37Z",
            "entitlements": {
              "canTriggerPrecisionAnalysis": false,
              "canManageTransactions": false,
              "canViewSurveys": false,
              "canViewOwnedSurveyResponses": true,
              "canViewSurveyResponsesOfTier1Suppliers": false,
              "canMutateOwnedSurveyResponses": false,
              "canDownloadSurveyResponses": false,
              "canManageWebhooks": false,
              "canAccessApi": false,
              "canManageCmsSupplierRiskAssessmentStatuses": false
            }
          }
        ],
        "connectionsAsSource": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "sourceBusiness": "[Circular Reference]",
            "targetBusiness": "[Circular Reference]",
            "createdAt": "2021-01-01T00:00:00.000Z",
            "updatedAt": "2021-01-01T00:00:00.000Z",
            "customData": {
              "foo": "bar"
            },
            "plotsCount": 1,
            "plotsCommodities": [
              "cattle",
              "cocoa"
            ]
          }
        ],
        "connectionsAsTarget": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "sourceBusiness": "[Circular Reference]",
            "targetBusiness": "[Circular Reference]",
            "createdAt": "2021-01-01T00:00:00.000Z",
            "updatedAt": "2021-01-01T00:00:00.000Z",
            "customData": {
              "foo": "bar"
            },
            "plotsCount": 1,
            "plotsCommodities": [
              "cattle",
              "cocoa"
            ]
          }
        ],
        "businessInvitations": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "sentByUser": "[Circular Reference]",
            "business": "[Circular Reference]",
            "email": "[email protected]",
            "status": "PENDING",
            "createdAt": "2020-01-01T00:00:00.000Z",
            "updatedAt": "2020-01-01T00:00:00.000Z",
            "sourceIsInvitee": "true",
            "customData": {
              "key1": "someValue",
              "key2": true,
              "key3": 1234
            }
          }
        ],
        "contactPerson": {
          "auth0UserId": "auth0|41ba-aa49-f114ca4c263f",
          "business": "[Circular Reference]",
          "businessId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
          "firstName": "Paul",
          "lastName": "Smith",
          "locale": "id-ID",
          "createdAt": "2023-07-26T15:03:48Z",
          "updatedAt": "2023-07-28T09:13:37Z",
          "completed": "false",
          "businessInvitations": "[Circular Reference]",
          "userInvitations": "[Circular Reference]",
          "email": "[email protected]",
          "consentedAt": "2023-07-28T09:13:37Z",
          "entitlements": {
            "canTriggerPrecisionAnalysis": false,
            "canManageTransactions": false,
            "canViewSurveys": false,
            "canViewOwnedSurveyResponses": true,
            "canViewSurveyResponsesOfTier1Suppliers": false,
            "canMutateOwnedSurveyResponses": false,
            "canDownloadSurveyResponses": false,
            "canManageWebhooks": false,
            "canAccessApi": false,
            "canManageCmsSupplierRiskAssessmentStatuses": false
          }
        },
        "machineToMachineClientId": "1234567890asdfghjk",
        "eori": "text",
        "vat": "text",
        "tracesEnvironment": "ACCEPTANCE"
      }
    ],
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            100,
            0
          ],
          [
            100.01,
            0
          ],
          [
            100.01,
            0.01
          ],
          [
            100,
            0.01
          ],
          [
            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": "PENDING",
      "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": "OS",
      "customData": {
        "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": "PENDING",
        "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": "OS",
        "customData": {
          "some": "metadata"
        },
        "name": "text"
      },
      "PRECISION": {
        "id": "02c36247-1aad-41ba-aa49-f114ca4c263f",
        "createdAt": "2023-07-26T15:03:48Z",
        "updatedAt": "2023-07-28T09:13:37Z",
        "status": "PENDING",
        "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": "OS",
        "customData": {
          "some": "metadata"
        },
        "name": "text"
      }
    },
    "riskAssessmentStatus": "NEW",
    "riskLevel": "none",
    "filename": {},
    "description": "text",
    "ownerId": "text",
    "customData": {
      "key1": "someValue",
      "key2": true,
      "key3": 1234
    }
  }
]

• Bulk-creates multiple plots of possibly different commodities

• Accepts GeoJSON payload conforming to a GeoJSON FeatureCollection

• Response format can be set with Accept header to either application/json (default) or application/geo+json for GeoJSON format

• Does not support partial failures ( if one plot does not pass validation, none of the plots will be created)

Deprecated

Bulk-create plots.

post

Create multiple plots that share the same commodities. The plots will be owned by your business. This endpoint is deprecated. Please use the POST /plots/batch/geojson endpoint instead.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

filenamestringOptional

Filename used to upload Plots in batch.

Responses

201Success

application/json

statusstringRequired

It describes the overall result of the batch operation.

Example: PARTIAL_FAILURE

errorsobjectRequired

Index and error detail for failed Plots.

Example: {"some_index_0":"some detailed error"}

processedobjectRequired

Index and endpoints for Plots processed successfully.

Example: {"some_index_0":"/plots/123"}

401Error

403Error

post

/plots/batch

HTTPcURLJavaScriptPython

POST /plots/batch HTTP/1.1
Host: api.tradeaware.live-eo.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 280

{
  "commodities": [
    "oil palm",
    "rubber"
  ],
  "filename": "text",
  "geometries": {
    "plot1": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            30,
            10
          ],
          [
            40,
            40
          ],
          [
            20,
            40
          ],
          [
            10,
            20
          ],
          [
            30,
            10
          ]
        ]
      ]
    },
    "plot2": {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [
              30,
              20
            ],
            [
              45,
              40
            ],
            [
              10,
              40
            ],
            [
              30,
              20
            ]
          ]
        ],
        [
          [
            [
              15,
              5
            ],
            [
              40,
              10
            ],
            [
              10,
              20
            ],
            [
              5,
              10
            ],
            [
              15,
              5
            ]
          ]
        ]
      ]
    }
  }
}

{
  "status": "PARTIAL_FAILURE",
  "errors": {
    "some_index_0": "some detailed error"
  },
  "processed": {
    "some_index_0": "/plots/123"
  }
}

• This endpoint is Deprecated. Please use POST /plots/batch/geojson instead.

• Bulk-creates multiple plots sharing the same commodities

• Accepts JSON payloads

• Returns a json object with success/failure status

• Supports partial failures (meaning some plots succeed while others might fail)