Skip to content

Working with Polygons

Polygons in the Vultus API are an area of land somewhere on the surface of the earth. Polygons in the agricutural context represent a plot of land, a field, or a farm and are the foundation of the Vultus API. Using the API you can register, activate, deactivate, delete, and list polygons.

Registering a Polygon with the API

Polygons have three user supplied attributes:

  1. coordinates
  2. a label
  3. a benefactor

Coordinates

Coordinates follow the GeoJSON polygon format in which the coordinates of the polygon follow the "right-hand rule" and holes in the polygon follow the "left-hand rule". All coordinates are written as [longitude, latitude]instead of the more familiar [latitude, longitude] of a tool like Google Maps. The first and last sets of coordinates must be identical in order to close the polygon.

The geojson.io website is an excellent tool for drawing a polygon and generating coordinates in the correct format.

Label

Labels are a way to provide descriptive information about the polygon. This is a free-form text field and is not required, though it is recommended.

Benefactor

The benefactor is a way for a user to identify the owner of a polygon. This provides users with a way to report on owner usage of the Vultus services. The value supplied for benefactor should be meaningful (a key, UID, etc.) to the user and should not contain personally identifiable information. Benefactor is a required attritube when registering a polygon.

generatePolygon()

The generatePolygon() mutation is used to register a polygon.

mutation{
  generatePolygon( 
    label: "Plot - 01", 
    benefactor: "farmer-01", 
    coordinates: [ 
      [ 
        [13.267485895061980, 55.66308798501626],
        [13.283366709725641, 55.67968156822468],
        [13.275276483396254, 55.68214803773702],
        [13.263231035305807, 55.66396684416060],
        [13.267485895061980, 55.66308798501626]
      ] 
    ] 
  ) 
  { 
    IsSuccess 
    Message 
    Status 
    Result { 
      polygonId 
      acres 
      hectares 
      geometry
      bbox
      center
    } 
  } 
}

A successful registration returns:

  • status information about the request,
  • a system generated polygonId, and
  • other polygon information as requested by the user

Retrieve Polygon Information

There are two queries that return detailed polygon information.

retrievePolygonDetails()

The retrievePolygonDetails() query provides the details of a single polygon.

query {
  retrievePolygonDetails(
    polygonId: "[YOUR POLYGON_ID GOES HERE]"
  )
  {
    Result {
      polygonId
      label
      benefactor
      hectares
      acres
      center
      bbox
      geometry
    }
  }
}

A successful query can return:

  • status information about the request, and
  • other polygon information as requested by the user

retrievePolygons()

The retrievePolygons() query provides the details of several polygons, based on the query parameters passed.

query {
  retrievePolygons(
    benefactor: "[YOUR BENEFACTOR GOES HERE]"
  )
  {
    Result {
      polygonId
      label
      benefactor
      hectares
      acres
      center
      bbox
      geometry
    }
  }
}

A successful query can return:

  • status information about the request, and
  • other polygon information as requested by the user

Activate, Deactivate, or Delete a Polygon

There two mutations used to activate and deactivate polygons. The mutations will activate or deactivate a single polygon. The active status is a way for users to prevent processing of polygons. The Vultus API will check the active status of a polygon before processing an analysis. If the polygon is inactive, the API will return a message stating:

Requests for inactive polygons cannot be processed. Please activate the polygon before sending the request again.

activatePolygon()

When a polygon is registered with the API, the active status is set to TRUE. The activatePolygon() mutation is used to re-activate an inactive polygon.

mutation {
  activatePolygon(
    polygonId: "[YOUR POLYGON_ID GOES HERE]"
  ) 
  {
    Status
    Message
    Result {
      isActive
      polygonId
    }
  }
}

deactivatePolygon()

The deactivatePolygon() mutation is used to deactivate an active polygon.

mutation {
  deactivatePolygon(
    polygonId: "[YOUR POLYGON_ID GOES HERE]"
  ) 
  {
    Status
    Message
    Result {
      isActive
      polygonId
    }
  }
}

If you try to activate an active polygon or deactivate an inactive polygon, the API will respond with a message stating the polygon is already active or inactive.

A successful mutatation can return:

  • status information about the request,
  • the polygonId, and
  • the current active status

deletePolygon()

The deletePolygon() mutation does not actually delete the polygon nor any of the associated data. The mutation only changes the delete status to TRUE. The polygon and associated data will be removed from the Vultus API three (3) months after the delete status is set to TRUE.

A polygon must first be set to "inactive". The deletePolygon() mutation is used to set the delete status to TRUE for an inactive polygon. You cannot change the delete status of an active polygon, nor can you reset the delete status of a deleted polygon. If you need to reset the delete status of a polygon, contact Vultus support for assistance.

mutation {
  deletePolygon(
    polygonId: "[YOUR POLYGON_ID GOES HERE]"
  ) 
  {
    Status
    Message
    Result {
      polygonId
    }
  }
}

If you try to delete an active polygon the API will respond with a message stating the polygon cannot be deleted.

A successful mutation returns the polygonId of the deleted polygon.

Calculating Polygon Size in Advance of Registration

calculatePlotMeasurements()

The calculatePlotMeasurements() query returns the plot area (acres, hectares, and square meters), the bounding box coordinates, and the center of the plot, based on the supplied coordinates. This query is useful when users are subjected to maximum area restrictions. You can use the coordinates supplied by the user to check the size of the plot prior to creating the plot with the generatePolygon() mutation.

Please refer to the Schema Documentation in the API Playground for more information.