Get Plantings

Plantings are the way to manage crop and field activity in the aWhere API. Use this API to record the type of crop, planting date, projections, and actuals to get the most out of our more advanced APIs. Over time, this API also enables historical metrics for any given field in the platform.

On This Page...

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/agronomics/plantings
  • Retrieves all the plantings in your account, for all fields, including any historical ones (non-current).
GET /v2/agronomics/fields/{fieldId}/plantings
  • Retrieves all the plantings for a specific field location, including any historical ones (non-current).
GET /v2/agronomics/fields/{fieldId}/plantings/{plantingId}
GET /v2/agronomics/fields/{fieldId}/plantings/current
GET /v2/agronomics/plantings/{plantingId}
  • Retrieves a specific planting by ID. IDs are issued by aWhere's APIs.
  • Replace {plantingId} with current to get only the most recent planting record for that field.
GET /v2/agronomics/plantings/current
  • Returns a list of all the current plantings from all field locations in your account.

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

Query Parameter Name Description Valid Values
limit The number of results to include on each of page of listed fields. Used in conjunction with offset to paginate.

Applies only to the Plantings List.
An integer number up to 120
offset The number of objects to skip before returning objects. Used in conjunction with offset to paginate. For example, if limit=50 and offset=50, then the API will be returning the second page of results.

Applies only to the Plantings List.
An integer up to the total number of results.
sort List of results can be sorted by any of the properties shown at right. See Sorting Conventions for more information.

Applies only to the Plantings List.
id
crop
field
plantingDate
harvestDate
crop Returns only the plantings in which a specific crop is planted.

Applies only to the Plantings List.
A valid crop ID from the Crops API
properties Only include these properties in the field location data. If not specified, then all properties are included by default. Any properties not listed at the right are always included.

Applies to all endpoints.
crop
field
plantingDate
projections
yield
harvestDate

Request Body

None

HTTP Headers

Remember to always send your OAuth2 Access Token in the Authorization header (see Authentication). This API doesn't require any additional headers.

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. Additionally, the APIs that return lists will return Content-Range header which is another way to know how many results are being shown and the total number of results. It looks like this:

Content-Range: {start}-{end}/{total} plantings

Response Body

Format for the Plantings List

{
 "plantings":[{
    "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}"}
          }
    },{ 
          ...
        }
     ],
 "_links":{
    "self":{"href":"{listSelfLink} "},
    "next":{"href":"{next_page}"},
    "prev":{"href":"{previous_page}"},
 }
}

Format for a Single Field

{
    "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.
{listSelfLink} The URI used to generate the list.
{next_page} The URI used to get the next page of results, using the same limit used for this request (default is 50). If there are no more results this property is not included.
{previous_page} The URI used to get the previous page of results, using the same limit used for this request (default is 50). If you're at the beginning of the list this property is not included.