ClearAg

Field Accessibility API

Iteris’ Field Accessibility API offers estimates of current and forecasted field conditions based on Iteris’ proprietary Land Surface Information System combined with machine-learning algorithms.

Field Accessibility

last updated 11/7/18

For organizations that strive to maximize operational efficiencies for their staff or customers, including optimum field accessibility timeframes for field equipment operations (i.e. planting, crop protection or nutrient product applications and other activities), this API offers estimates of current and forecasted field conditions based on Iteris' proprietary Land Information System combined with machine-learning algorithms. This service is available for any location worldwide and provides data for up to 240 hours beginning with the current hour.

Multiple data center regions are available to meet users' legal and performance needs. Currently, data centers exist within the United States (ag.us.clearapis.com) and the European Union (ag.eu.clearapis.com). Account and related information such as fields and growths are not shared between these regions. Data resolution and availability also vary by region, and each region requires a unique set of credentials. Please contact your account representative for account creation, data segregation, and data coverage information.

Please note that API responses are currently only provided in English.

Iteris requires the use of https when working within the ClearAg APIs.

This service requires the Accounts API for creating and managing field locations, and to provide feedback.

Additional API information is available in the Appendix.

Hourly Field Accessibility - v1.2

The field accessibility service offers estimates of current and forecasted field conditions. The field accessibility classification provides an estimate of whether or not the field conditions are favorable to perform field operations. A "Good" classification means the field conditions are favorable for field operations; a "Marginal" classification means the field may not be appropriate for field operations; and a "Poor" classification rating means the field conditions are inappropriate for field operations.

URL Description

https://ag.us.clearapis.com/v1.2/field_accessibility/hourly?app_id={string}
&app_key={string}&account_id={string}&user_id={string}&field_id={string}
&start_offset={integer}&end_offset={integer}&start_time={integer}
&end_time={integer}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the provided field_id.

field_id

string

yes

Field ID provided by and used with the Accounts API. This ID is given when a field is successfully registered through the Accounts API.

start_offset

integer

yes3

Hours offset from the top of the current hour. Negative and positive offsets are valid. Hour 0 represents the top of the current hour. Requires "end_offset" also be provided. Cannot be provided in conjunction with "start_time" or "end_time." A maximum range of 240 (+1 if hour 0 is in range) hours can be returned per call. Cannot exceed value of 240.

end_offset

integer

yes3

Hours offset from the top of the current hour. Negative and positive offsets are valid. Requires that "start_offset" also be provided. Cannot be provided in conjunction with "start_time" or "end_time." Cannot exceed value of 240.

start_time

integer

yes3

Epoch timestamp representing start of range selection. Requires "end_time" also be provided. Value must be positive. Requires "end_time" also be provided. Cannot be provided in conjunction with "start_offset" or "end_offset." A maximum range of 240 (+1 if hour 0 is in range) hours can be returned per call. Cannot exceed 240 hours from top of current hour. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

end_time

integer

yes3

Epoch timestamp representing end of range selection. Requires "end_time" also be provided. Value must be positive. Requires "end_time" also be provided. Cannot be provided in conjunction with "start_offset" or "end_offset." Cannot exceed 240 hours from top of current hour. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

3 Denotes special rules for if a parameter is required or not.

Response Object (JSON)

Field Description

field_accessibility/ accessibility_id

An enumerated representation of the field conditions. This is passed to the Field Accessibility Feedback endpoints.

field_accessibility/ classification

A textual representation of the field conditions. Possible values include "Poor," "Marginal," or "Good."

field_accessibility/ value

A numerical representation of the field conditions. Possible values range from -1 to 1, with small negative or positive values indicating marginal field conditions, values closer to -1 indicating poor conditions, and values closer to 1 indicating good conditions.

field_metadata/ field_id

Field ID provided by the Accounts API.

field_metadata/ growth_id

Growth ID provided by the Accounts API.

field_metadata/ latitude

Latitude coordinate of the field location obtained from the Accounts API. Please verify that latitude/longitude coordinates are over soil representative of your field.

field_metadata/ longitude

Longitude coordinate of the field location obtained from the Accounts API. Please verify that latitude/longitude coordinates are over soil representative of your field.

field_metadata/ model_id

An identification of the numerical model that produced the result. This is passed to the Field Accessibility Feedback endpoints.

field_metadata/ user_id

User ID provided by the Accounts API.

Example Request

https://ag.us.clearapis.com/v1.2/field_accessibility/hourly?app_id=123&app_key=321
&account_id=abc&user_id=xyz-123&field_id=321-abc&start=0&end=240

Example Response

{
    "data":{
        "321-abc":{
            "field_data":{
                "1463601600":{
                    "field_accessibility":{
                        "accessibility_id":2,
                        "classification":"Poor",
                        "value":-1
                    }
                },...
            },
            "field_metadata":{
                "field_id":"321-abc",
                "growth_id":null,
                "latitude":"47",
                "longitude":"-97",
                "model_id":"987-lmn",
                "user_id":"xyz-123"
            }
        }
    }
}

Field Accessibility Add Feedback - v1.0

By providing feedback related to field accessibility, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field feedback is being added.

URL Description

https://ag.us.clearapis.com/v1.0/field_accessibility/hourly/feedback/add/
{field_id}/{model}/{timestamp}/{observed_field_accessibility_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

field_id

string

yes

Field ID provided by and used with the Accounts API. This ID is given when a field is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

observed_field_ accessibility_id

string

yes

An enumerated value of the observed field accessibility. Valid values: 2 is poor, 1 is good, and 3 is marginal.

model

integer

yes

The model_id returned by the field accessibility advisory service.

Response Object (JSON)

A string representing a feedback ID.

Example Request

https://ag.us.clearapis.com/v1.0/field_accessibility/hourly/feedback/add/
abc-def/456-789/1493632000/3?app_id=456&app_key=789&account_id=123
&user_id=xyz-123

Example Response

def-345

Appendix

Common HTTP response codes

The following are common HTTP response codes and their meanings. These are standard across all API services.

  • 200 OK - The request was successful.

  • 400 Bad Request - The request was invalid. An accompanying error message will be provided if available.

  • 401 Unauthorized - Authentication to the API has failed. Authentication credentials are missing or incorrect.

  • 403 Forbidden - You are trying to access a resource for which you do not have the appropriate privileges.

  • 404 Not found - The requested resource was not found. An accompanying error message will be provided if available.

  • 500 Internal Server Error - An internal server error has occurred while processing the request.

  • 502 Bad Gateway - The service is not reachable.

Null or Empty Values

In some cases values will be represented as "n/a." This indicates that the requested data is not available or is not applicable.

Epoch/Unix Timestamp

Iteris employs Epoch/Unix timestamps for some time-based parameters. Timestamps are defined as the number of seconds since 1970-01-01 00:00 Coordinated Universal Time (UTC).

Note that in daily endpoints, timestamps as URL arguments do not necessarily conform to this definition. In these endpoints, timestamps can be thought of as being relative to the local time zone. For example, a plant_date timestamp corresponding to 2016-05-01 00:00 UTC in the Corn Growth endpoint can be viewed as 2016-05-01 00:00 local time, and the endpoint returns data starting on that date.

Regional-based Account Access

Any data stored by the Account API in one region is not available in another. Each region will require a unique set of credentials. Please contact your account representative if interested in utilizing an additional region. When attempting to use the credentials from one region with the services in another, an 'account not found' error will be returned with HTTP status code 400. See example below:

<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>Account not found.</p>

Feedback Information

The feedback timestamp, which is the precise time when the feedback was observed, must happen after the plant/emergence date and prior to the current date. Growth feedback is considered (confirmed) if the stage of feedback occurs before the model anticipates. If there are multiple feedbacks for a given stage, the feedback with the most recent feedback timestamp will take precedence. If more than one feedback with the same stage and the same feedback timestamp are present, then the system will use the feedback with the most recent created timestamp.

Changelog

This section describes document changes occurring in the two most recent versions.