Update All or Part of a Planting in a Field

You are here:
< All Topics
image_pdfDownload as PDF

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.

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

PARAMETERDESCRIPTIONVALID 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

NAMEDESCRIPTIONVALID VALUESREQUIRED?
{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 APIYes
{plantingDate}The date the crop was planted in the field.A date stamp formatted as YYYY-MM-DDYes
{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 stringNo
{projectedHarvestDate}The projected harvest date at the start of the season.A date in the format YYYY-MM-DDNo
{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 stringNo
{harvestDate}The actual harvest date at the end of the season.A date in the format YYYY-MM-DDNo

HTTP Headers

HEADER NAMEREQUIRED VALUE
AuthorizationBearer {token} (see Authentication)
Content-Typeapplication/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

NAMEDESCRIPTION
{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.
projectionsUse 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.
Was this article helpful?
0 out Of 5 Stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
How can we improve this article?
Table of Contents