Update All or Part of a Planting in a Field

Occasionally you will need to update a planting, changing the projections or recording the end-of-season information for historical tracking and model tuning. This API supports both partial and complete updates of plantings.

When updating an entire planting, the whole object is replaced in the database. Any properties that were previously set, and now are not, will be null'd. The required properties must also be set even if they are changed.

On This Page...

API Request

API Endpoints

HTTP Verbs and URIs

PUT /v2/agronomics/fields/{fieldId}/plantings/{plantingId}
PUT /v2/agronomics/fields/{fieldId}/plantings/current
  • Updates an entire planting, replacing the whole object in the database.
  • Use current instead of {plantingId} as a short cut for updating only the most recent planting in a field.
PATCH /v2/agronomics/fields/{fieldId}/plantings/{plantingId}
PATCH /v2/agronomics/fields/{fieldId}/plantings/current
  • Updates only specific properties of the planting record, using the PATCH HTTP Method.
  • Request bodies are formatted as JSON-PATCH requests. Read on for more detailed explanations of how to make updates to your fields.
  • Use current instead of {plantingId} as a short cut for updating only the most recent planting in a field.

Parameters

Parameter Description Valid Values
{fieldId} The ID of the field that you used when you created it. A string
{plantingID} The ID of the planting issued by aWhere's API with the planting was created. A string

Query String Parameters

None.

Request Body

For Updating a Whole Planting (PUT)

{
    "crop":"{crop}",
    "plantingDate":"{plantingDate}",
    "projections":{
        "yield":{
            "amount":{projectedYieldAmount},
            "units":"{projectedYieldUnits}",
            }
        "harvestDate":"{projectedHarvestDate}"
        }
    "yield":{
        "amount":{yieldAmount},
        "units":"{yieldUnits}",
        },
    "harvestDate":"{harvestDate}"
}

For Updating Only Specific Properties of a Planting (PATCH)

Request bodies are formatted as JSON-PATCH requests. A JSON-PATCH request is a sequence of changes you want to make to your field location. Example:

[
    { "op":"replace",
      "path":"/name",
      "value":"NorthWest-40"
    },
    {
      "op":"replace",
      "path":"/farmId",
      "value":"A-42441"
    }
]

There are three properties in each command:

  • op—the operation being executed. This API supports two:
    • test determines if the saved value matches the command value
    • replace changes the saved value to the command value
  • path—The property being tested or changed. In this API, only top-level properties can be changed, so this value is either /name or /farmId
  • value—The command value that is either being tested or will be saved to the field location.

The commands in the sequence are executed in order, and every item in the sequence must complete successfully or else none of the changes will be saved. You can combine "test" and "replace" operations in a sequence, so that a change is only saved if the test passes.

Property Descriptions

Name Description Valid Values Required?
{crop} Every planting must have a crop associated with it and this crop must come from the Crops API. When creating a planting you may specify either the actual crop ID, or if you don't know or care about a specific crop type/variety, you may simply use the crop name (such as "corn" or "wheat") and the API will select the default record for that category. A crop ID or valid Name from the Crops API Yes
{plantingDate} The date the crop was planted in the field. A date stamp formatted as YYYY-MM-DD Yes
{projectedYieldAmount}
and
{projectedYieldUnits}
The projected yield can be any amount and any units (bushels, boxes, etc). This is an optional set of fields, but if one is set the other must be as well. A string No
{projectedHarvestDate} The projected harvest date at the start of the season. A date in the format YYYY-MM-DD No
{yieldAmount}
and
{yieldUnits}
The actual yield can be any amount and any units (bushels, boxes, etc). This is an optional set of fields, but if one is set the other must be as well. A string No
{harvestDate} The actual harvest date at the end of the season. A date in the format YYYY-MM-DD No

HTTP Headers

Header Name Required Value
Authorization Bearer {token} (see Authentication)
Content-Type application/json

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. No additional headers are returned.

Response Body

After a field location is created, the API will return the same body as the Get Single Planting endpoint.

{
    "id": {id},
    "crop":"{cropId}",
    "field":"{fieldId}",
    "plantingDate":"{plantingDate}",
    "projections":{
        "yield":{
            "amount":{projectedYieldAmount},
            "units":"{projectedYieldUnits}",
            }
        "harvestDate":"{projectedHarvestDate}"
        }
    "yield":{
        "amount":{yieldAmount},
        "units":"{yieldUnits}",
        },
    "harvestDate":"{harvestDate}",
    "_links":{ 
        "self":{"href":"{plantingSelfLink}"},
        "curies":[{
            "name":"awhere",
            "href":"http://awhere.com/rels/{rel}",
            "templated":true
            }],
        "awhere:field":{"href":"{fieldLink}"}
        "awhere:crop":{"href":"{cropLink}"}
    }
}

Property Descriptions

Name Description
{id} The Planting ID. Planting IDs are numeric and issued by aWhere
{cropId} The ID of the crop planted in this field.
{plantingDate} The date the crop was planted in the field.
projections Use the projections array to record pre- and early-season estimates of what is expected from the field. Then at the end of the season your application can easily track how well the field performed. aWhere can use use this information to help tune models as well.
{projectedYieldAmount}
and
{projectedYieldUnits}
The projected yield can be any amount and any units (bushels, boxes, etc).
{projectedHarvestDate} The estimated date when the harvest will be ready. This can be changed as the season progresses.
{yieldAmount}
and
{yieldUnits}
The actual yield can be any amount and any units (bushels, boxes, etc).
{harvestDate} The actual harvest date at the end of season, this is useful for historical data tracking.
{plantingSelfLink} The URI of the each planting location object.
{fieldLink} The URI of the relevant field for each planting.
{cropLink} The URI of the crop recorded for each planting.