Create a Planting in a Field

Creating a planting will provide the aWhere platform the information needed to run models and more efficiently calculate agronomic values. You can also use these properties to record projections for the field, like yield or harvest date, to track the success of a field over the course of a growing season. Recording projected and actual yield and harvest date also helps aWhere tune the models for even greater accuracy.

There can only be one active planting per field. You can create multiple plantings per field but only the most recent one will be considered the "current" one. Use this functionality to create historical records if you have them.

When creating a planting, you must specify the crop and planting date. The crop must be an option from the Crops API; but there is also a short cut where if you don't know or want to use a specific crop ID, you can simply specify the crop name, such as "corn" or "wheat" and the the API will select the default for that category.

On This Page...

API Request

API Endpoints

HTTP Verbs and URIs

POST /v2/agronomics/fields/{fieldId}/plantings
  • Create a planting in a field location.

Query String Parameters

None.

Request Body

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

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. Additionally, this endpoint will return Location header provides the URL of the newly created data record. It looks like this:

Location: https://api.awhere.com/v2/agronomics/fields/{fieldId}/plantings/{plantingId}

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.