Get Field Locations

Fields are the way to manage the locations you use in the aWhere API, before using our other APIs you'll need to register the field locations. This is a one-time step. Every field has an ID that you define, plus a latitude and longitude. Fields are universal across all our APIs, and as you provide information about a field, some APIs (such as agronomics and models) can leverage that detail internally to more easily and seamlessly calculate information for you.

On This Page...

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/fields
  • This is known as the Fields List endpoint; it retrieves all the field locations in your account.
  • By default, 50 fields will be included in each page of the list, but you can change this with query string parameters.
GET /v2/fields/{fieldId}
  • This is the Single Field endpoint; it retrieves a specific field location.

Parameters

Parameter Description Valid Values
{fieldId} The ID of the field that you used when you created it. Field IDs are arbitrary strings that you specify, they could be a number (like a row ID from your database), or a short name. 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 Fields List.
An integer number up to 120
offset The number of objects to skip before returning objects. Used in conjunction with limit 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 Fields 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 Fields List.
name
farmid
acres
latitude
longitude
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 both endpoints.
name
farmid
acres
centerpoint

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 Fields 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} fields

Response Body

Format for the Fields List

{
 "fields":[{
    "id": "{fieldId}",
    "name":"{fieldName}",
    "farmId":"{farmId}",
    "acres":{acres},
    "centerPoint":{
        "latitude":{latitude},
        "longitude":{longitude},
        },
    "_links":{ 
        "self":{"href":"{field_self}"}
    }
    },{ 
      ...
    }
 ],
 "_links":{
    "self":{"href":"{list_self}"},
    "next":{"href":"{next_page}"},
    "prev":{"href":"{previous_page}"},
 }
}

Format for a Single Field

{
    "id": "{fieldId}",
    "name":"{fieldName}",
    "farmId":"{farmId}",
    "acres":{acres},
    "centerPoint":{
        "latitude":{latitude},
        "longitude":{longitude},
        },
    "_links":{ 
        "self":{"href":"{field_self}"}
    }
}

Property Descriptions

Name Description
{fieldId} The ID you specified for the field, you'll use this in most aWhere APIs when selecting a location.
{fieldName} The name you specified for the field, which could be shown in a dropdown box or list.
{farmId} The ID for the farm that owns this field. You'll specify this when you create the field.
{acres} The size of the field in acres.
{latitude}
and
{longitude}
The geolocation associated with the field, typically the centerpoint.
{field_self} The URI of the each field location object.
{list_self} 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.