Crops List and Detail

Models are designed for specific crops, and often specific types or varieties of crops. This API provides the list of available crops. When creating a planting record, you're encouraged to specify the crop that is planted in the field using these records.

Every Crop record represents the unique combination of crop name, type, and variety. The name of the crop is the common name most people use, such as "corn" or "wheat." The type and variety are more specific classifications.

Within each category of crop (organized by name), there is a default crop. When creating a planting, you may not know or care about the specific variety, and can simply specify the crop name as what is planted there. When you do this, the system will use the default crop for that category. You'll know which crop record is the default by referencing the isDefaultForCrop property, described below.

On This Page...

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/agronomics/crops
  • Returns a list of available crops in the platform.
  • Use query string parameters to filter the list (see below).
GET /v2/agronomics/crops/{cropId}
  • Retrieves a specific crop.

Parameters

Parameter Description Valid Values
{cropId} The ID of the crop you wish to reference. Crop IDs are strings provided by the aWhere APIs. 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 Crops 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 Crops 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 Crops List.
id
name
type
variety
properties Only include these properties in the response. If not specified, then all properties are included by default. Any properties not identified in the list to the right are always included. name
type
variety
isDefaultForCrop
crop Filter the list of models to only those with in a category, as determined by the crop name (e.g., "corn"). Any value found in the name property

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 Crops List 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} crops

Response Body

Format for the Models List

{
 "crops":[{
    "id":"{id}",
    "name":"{name}",
    "type":"{type}",
    "variety":"{variety}",
    "isDefaultForCrop":{isDefaultForCrop},
    "_links":{ 
        "self":{"href":" {cropSelfLink}"},
        "curies":[{
            "name":"awhere",
            "href":"http://awhere.com/rels/{rel}",
            "templated":true
            }],
        "awhere:plantings":{"href":"{plantingsLink}"}
    }
    },{ 

 }],
 "_links":{
    "self":{"href":"{listSelfLink}"},
    "next":{"href":"{next_page}"},
    "prev":{"href":"{previous_page}"},
 }
}

Note: When requesting just a single crop, the response is only a single crop object, shown here as the first object in the crops array.

Property Descriptions

Name Description
{id} The Crop ID. Use this to reference the crop in other APIs.
{name} The crop name, which could be shown in a dropdown box or list. This is the common name for the crop, such as "corn" or "wheat." All crop records will always have a name.
{type} A more specific classification of the crop, such as "Hard Red Wheat." Not all crop records have a type, and when they don't this value is null or "generic."
{variety} A more specific classification of the crop, such as "long season" or "short season." Not all crop records have a variety, and when they don't this value is null or "generic."
{isDefaultForCrop} Some other APIs allow the selection of a crop record by name only. When this is done, the platform will select the default record for each category. This value is a boolean indicator of whether the record is the default.
{cropSelfLink} The URI of the each crop object.
{plantingsLink} The URI of the Plantings API, set to filter only those plantings with this crop specified.
{listSelfLink} The URI used to generate the list, which includes any current pagination parameters.
{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.