search

Plots

hashtag
List all plots.

get

Lists all plots of your business.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
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

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, riskLevel. Deprecation: 'mostRecentAnalysis' is deprecated. Please use 'mostRecentAnalysesByType' as the response data will in particular include the data from 'mostRecentAnalysis'.

Example: mostRecentAnalysesByType
Header parameters
acceptstring · enumOptional

Specify the response format. Defaults to application/json.

Possible values:
Responses
chevron-right
200

All plots in a list or as a GeoJSON FeatureCollection

or
get
/plots

  • Lists all plots of your business with pagination support

  • Supports includes:

    • mostRecentAnalysis (deprecated) - returns the latest analysis for a plot

    • mostRecentAnalysesByType - returns the latest precision and latest os analysis for a plot

    • suppliers - result will include plots of suppliers and sub-suppliers.

  • Supports pagination

  • Support filtering by commodity

  • Support sorting by createdAt

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

  • Note: Using both mostRecentAnalysis and mostRecentAnalysesByType in includes simultaneously is not supported.

hashtag
Create a plot.

post

Create a plot owned by your business using JSON or GeoJSON format.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Header parameters
acceptstring · enumOptional

Specify the response format. Defaults to application/json.

Possible values:
Body
or
Responses
post
/plots

  • Creates a single plot owned by the user's business

  • Request format can be set with Content-Type header and should adhere to

    • Content-Type=application/json (default) or

    • Content-Type=application/geo+json for payloads in GeoJSON format.

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

hashtag
Retrieve a plot.

get

Retrieve the specified plot.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Query parameters
includesanyOptional

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

Example: mostRecentAnalysis,mostRecentAnalysesByType,riskLevel
Header parameters
acceptstring · enumOptional

Specify the response format. Defaults to application/json.

Possible values:
Responses
chevron-right
200Success
or
get
/plots/{id}

  • Retrieves a specific plot by UUID

  • Supports includes:

    • mostRecentAnalysis

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

hashtag
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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Header parameters
acceptstring · enumOptional

Specify the response format. Defaults to application/json.

Possible values:
Body
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.

geometryobjectOptional

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

isActivebooleanOptional

Is this plot active in the system

Default: true
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}
areaHanumber · min: 0.1 · max: 4Optional

The area of the plot or production place in hectares (ha).

Only applicable when the geometry is a GeoJSON point.
- must be between 0.01 and 4 hectares
- defaults to 4 hectares if not specified

If the geometry is a polygon, this value will be ignored as the area is calculated from the polygon itself
Default: 4Example: 0.5
Responses
chevron-right
200Success
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

riskAssessmentStatusall ofOptional

The risk assessment status of this plot set by your business

string · 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}
patch
/plots/{id}

  • Updates an existing plot

  • Accepts only JSON payload with Content-Type=application/json

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

hashtag
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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Responses
delete
/plots/{id}
No content
PreviousAuthNextAnalyses of a specific Plot

Last updated