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.
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
200
All plots in a list or as a GeoJSON FeatureCollection
401Error
403Error
501
Using the query parameter 'includes' with 'mostRecentAnalysesByType' and 'mostRecentAnalysis' simultaneously is not supported. 'mostRecentAnalysis' is deprecated. Please only use 'mostRecentAnalysesByType' as the response data will in particular include the data from 'mostRecentAnalysis'.
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.
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
201
Returns the created plot
401Error
403Error
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
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.
Example: mostRecentAnalysis
Header parameters
acceptstring · enumOptional
Specify the response format. Defaults to application/json.
Possible values:
Responses
200Success
Responseone of
or
401Error
403Error
404Error
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
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.
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'
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
200Success
401Error
403Error
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
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>.
