Update a Field Location

Occasionally, you may need to update a field location detail. Only the Farm ID and Field Name can be updated at this time.

Because this API only supports partial updates, we use the PATCH HTTP Method and request bodies are formatted as JSON-PATCH requests. Read on for more detailed explanations of how to make updates to your fields.

API Request

API Endpoints

HTTP Verbs and URIs

PATCH /v2/fields
  • Update specific properties of a field location (name or farm ID).

Query String Parameters

None.

Request Body

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. See the Examples below.

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. No additional headers are returned.

If the update fails, perhaps because a test condition did not pass, or if you attempt to update a property that cannot be edited, a 400 Bad Request status code is returned.

Response Body

After a field location is updated, the API will return the same body as the Get Single Field endpoint.

{
    "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.
{self} The URI of the each field location object.
{field_self} The URI of the each field location object.

Example: Test and Replace Combination

In this example, the request is testing to see if the current value is equal to "North40" and if so, then the value will be changed to "NorthWest40." If the test fails, then the update will not complete.

Request

Endpoint

PATCH /v2/fields/field123

Body

[
    {"op":"test","path":/name","value":"North40"},
    {"op":"replace","path":/name","value":"NorthWest40"}
]

Response

Body

{
    "id": "field123",
    "name":"NorthWest40",
    "farmId":"A-12345",
    "acres":null,
    "centerPoint":{
        "latitude":39.7096116,
        "longitude":-105.1045942,
        },
    "_links":{ 
        "self":{"href":"/v2/fields/field123"}
    }
}