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 4/1/19

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.

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

Unix timestamp representing start of range selection. Requires "end_time" also be provided. Value must be positive. 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.

end_time

integer

yes3

Unix timestamp representing end of range selection. Requires "start_time" also be provided. Value must be positive. Cannot be provided in conjunction with "start_offset" or "end_offset." Cannot exceed 240 hours from top of current hour.

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

Unix timestamp representing the date for which the feedback applies.

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

Field Accessibility Delete Feedback - v1.0

This endpoint allows a user to delete an existing field accessibility feedback.

URL Description

https://ag.clearapis.com/v1.0/field_accessibility/hourly/feedback/delete/
{field_feedback_id}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris upon account creation.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by an Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

field_feedback_id

string

yes

ID of target field feedback to modify.

Response Object

A string representing success ("true") or failure ("false").

Example Request

https://ag.us.clearapis.com/v1.0/field_accessibility/hourly/feedback/delete/aaa-bbb?account_id=111-222&user_id=333-444&app_id=123&app_key=321

Example Response

true

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.

Unix Timestamp

Iteris employs Unix timestamps for some time-based parameters. Unix timestamps are defined as the number of seconds since 1970-01-01 00:00 Coordinated Universal Time (UTC), and are an absolute and universal measure of time, independent of timezones. For example, when the current Unix time is 1457543400, it is 1457543400 everywhere, whether it is the middle of the night or middle of the day at any particular location on Earth.

When requesting hourly or sub-hourly data, the use of Unix timestamps is straightforward. Simply convert the desired date/time/timezone into its corresponding Unix timestamp, and pass the resulting value in via the URL associated with the API request. For instance, if you wish to retrieve hourly data for the period spanning 2001-03-09 12:00 Central Standard Time (CST) to 2001-03-10 12:00 CST, you would pass in Unix timestamps of 984160800 and 984247200, respectively.

When requesting daily data, however, the use of Unix timestamps is less straightforward. Ideally, the Unix timestamps provided would be evaluated in the timezone of the requested location in order to interpret the date ranges desired from the request. However, since many of Iteris’ API endpoints permit requesting data for many different locations in a single query, the timezone may vary between the different locations included in the query. If the Unix timestamps were evaluated in the local timezone of each of the query locations, there would be instances when the data returned would be for a date range that is shifted by a day between the different locations, which is generally an undesirable behavior. For example, while 984160800 evaluates to 2001-03-09 in Central Standard Time (CST; which is equivalent to UTC-6), it evaluates to 2001-03-10 in New Zealand (UTC+12).

Because of this, when Unix timestamps are used in queries for daily data, the method employed by Iteris is to do all conversions between Unix timestamps and year/month/day assuming the timezone is UTC (equivalent to UTC+0). If you desire daily data for 2001-03-09, you must pass in a Unix timestamp that falls within the range 984096000 (corresponding to 2001-03-09 00:00 UTC) and 984182399 (2001-03-09 23:59:59 UTC). It is generally easiest to find an appropriate Unix timestamp by just converting the date/time/timezone string of “YYYY-MM-DD 00:00 UTC” replacing the year (YYYY), month (MM), and day (DD) as desired. If you wish for any particular date to be included, the Unix timestamps provided for the start and end of the query must encapsulate that date when evaluated in the UTC+0 timezone.

It is important to note that while the system Iteris employs for converting Unix timestamps in query URLs into the associated date ranges operates under the assumption of a UTC+0 timezone for daily data requests, the data that are returned from the requests are aligned to midnight-to-midnight local time in the timezone of each location contained in the request. For example, if locations in the Central and Mountain timezones of the United States are included in the same request, the data from locations falling in the Central timezone would be valid for the period spanning midnight-to-midnight CST (Central Standard Time), while the data from locations falling in the Mountain timezone would be valid for the period spanning midnight-to-midnight MST (Mountain Standard Time). Thus, if one were to create any sort of spatial display of data returned from Iteris’ daily data endpoints, the boundaries between timezones may be evident (for instance if rain fell in the hour prior to midnight immediately on the west side of the timezone boundary, while it fell in the hour following midnight immediately on the east side of the timezone boundary).

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>

Changelog

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

4/1/19

Text updates to introductory section.

3/19/19

Added the Field Accessibility Delete Feedback endpoint.