Usage

Working with Polygons

Polygons represent your field boundaries and are the foundation of every analysis. This page covers all polygon operations: creation, retrieval, activation, and deletion.

Create a Polygon

Use generatePolygon() to register a new field boundary. Coordinates must be in GeoJSON format: [longitude, latitude] pairs, with the first and last coordinate being identical to close the ring.

GraphQL Mutation

mutation { generatePolygon( label: "South Pasture" benefactor: "my-farm" coordinates: [ [10.4015, 63.4305], [10.4065, 63.4305], [10.4065, 63.4275], [10.4015, 63.4275], [10.4015, 63.4305] ] ) { polygonId label acres hectares geometry } }

Parameters

label REQUIRED

Human-readable name for the polygon.

benefactor REQUIRED

Identifier for the owner or organization. Used to group and retrieve polygons.

coordinates REQUIRED

Array of [longitude, latitude] coordinate pairs. The ring must be closed (first coordinate equals last).

Retrieve Polygon Details

Get information about a specific polygon by its ID:

GraphQL Query

query { retrievePolygonDetails( polygonId: "abc123-def456-ghi789" ) { polygonId label benefactor acres hectares active geometry } }

List All Polygons

Retrieve all polygons belonging to a specific benefactor:

GraphQL Query

query { retrievePolygons( benefactor: "my-farm" ) { polygonId label acres hectares active } }

Activate and Deactivate

Polygons can be activated or deactivated to control whether they are available for analysis:

GraphQL Mutations

// Activate a polygon mutation { activatePolygon(polygonId: "abc123-def456-ghi789") { polygonId active } } // Deactivate a polygon mutation { deactivatePolygon(polygonId: "abc123-def456-ghi789") { polygonId active } }

Delete a Polygon

Remove a polygon permanently. The polygon must be inactive before it can be deleted.

GraphQL Mutation

mutation { deletePolygon(polygonId: "abc123-def456-ghi789") { Status Message } }

Warning: Deleted polygons are fully removed after 3 months. During this period, associated data may still be accessible. Only inactive polygons can be deleted.

Pre-registration Validation

Use calculatePlotMeasurements() to validate coordinates before creating a polygon. This returns the area and perimeter without registering anything.

GraphQL Query

query { calculatePlotMeasurements( coordinates: [ [10.4015, 63.4305], [10.4065, 63.4305], [10.4065, 63.4275], [10.4015, 63.4275], [10.4015, 63.4305] ] ) { acres hectares perimeter } }

Tip: Always validate coordinates with calculatePlotMeasurements() before registering. This helps catch coordinate order mistakes and ensures the polygon area is within API limits.