Introduction

Welcome to the Iteris ClearAg Accounts API. This system allows API integrators to create and utilize users, fields, and growths within the ClearAg family of APIs. In addition, this API offers several services for providing information about fields and growths that, in return, provide even greater accuracy and value for users.

Please note that before users can access the ClearAg Accounts API, an active account and license key is required. These credentials will be provided for each service request. To obtain your API key, contact your Iteris account representative.

API Services

The ClearAg Accounts API allows users to edit, add, and delete information related to user access, field details, and growth specifications. Each of the following endpoints outlines the given action and the information necessary when working in the API. If using the Accounts API in conjunction with the Crop Health API, please refer to the Crop Health API documentation for additional information.

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. Please contact your account representative for account creation and data segregation information.

Additional API information, such as details on supported unit sets and API behavior, is available in the Supplementary API Information section of the Appendix.

1. Users

A unique user ID must be used when performing any action within the Accounts API. The endpoints documented below provide a means of creating and managing user information.

1.1. Create User - v1.0

After first obtaining an account ID provided by Iteris, the Create User endpoint allows for the creation of a user within an account. Once the user is created, a user ID is provided that will be needed to perform most operations within the system. Note that multiple users may be added using a single account ID.

1.1.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/user/create?app_id={string}
&app_key={string}&account_id={string}&name={string}&email={string}

1.1.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by an Iteris account representative.

name

string

no

New user’s name.

email

string

no

New user’s email address.

1.1.3. Response Object

A string representing a new user ID.

1.1.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/user/create?app_id=123
&app_key=321&account_id=123&name=JoeSmith&email=joe_smith@smith.com

1.1.5. Example Response

xyz-123

1.2. Modify User - v1.0

The Modify User endpoint allows changes to various user properties. Currently any user within an account can modify other users in the same account. User rights management is the responsibility of the consuming application.

1.2.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/user/modify/{target_user_id}?
app_id={string}&app_key={string}&account_id={string}
&user_id={string}&name={string}&email={string}

1.2.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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.

target_user_id

string

yes

Specifies ID of user to be modified.

name

string

no

The name of the user. The user must supply at least one of the “name” or “email” parameters in the URL.

email

string

no

The email address of the user. The user must supply at least one of the “name” or “email” parameters in the URL.

1.2.3. Response Object

A string representing success (“true”) or failure (“false”).

1.2.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/user/modify/abc-123?
app_id=123&app_key=321&account_id=123&name=JoeSmith
&email=joe_smith@smith.com

1.2.5. Example Response

true

1.3. Remove User - v1.0

The Remove User endpoint allows for the deletion of a user from Iteris’ user information database. Currently, any user within an account can modify other users in the same account. User rights management is the responsibility of the consuming application.

1.3.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/user/delete/{target_user_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

1.3.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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.

target_user_id

string

yes

Specifies ID of user to be removed from the user information database.

1.3.3. Response Object

A string representing success (“true”) or failure (“false”).

1.3.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/user/delete/xyz-123?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

1.3.5. Example Response

true

1.4. Get User Information - v1.0

The Get User Information endpoint functions as a medium to obtain information on users registered to an account.

1.4.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/user/info/{target_user_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

1.4.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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.

target_user_id

string

yes

Specifies ID of user to be queried.

1.4.3. Response Object (JSON)

Field Description

account_id

A unique account ID provided by an Iteris account representative.

email

The email address of the user.

name

The name of the user.

user_id

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

1.4.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/user/info/xyz-123?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

1.4.5. Example Response

{
    "account_id":"123",
    "email":"joesmith@jsmith.com",
    "name":"Joe Smith",
    "user_id":"xyz-123"
}

2. Field

Several endpoints provided by the Accounts API, including the Create Field, Modify Field, Delete Field, and Get Field Information endpoints, provide users with the ability to add and manage field information. Field information is required for our models to process events.

2.1. Create Field - v1.0

The Create Field endpoint serves as a means of entering a new field into Iteris’ user information database, attributed to a single account ID and user ID. Users are required to provide such information as approximate field latitude-longitude coordinates and acreage, and may optionally provide additional information about the field, such as drainage quality, irrigation type, and field name.

2.1.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/create?
app_id={string}&app_key={string}&account_id={string}
&user_id={string}&acres={float}&latitude={float}&longitude={float}
&name={string}&type={integer}&subtype={integer}
&subsurface_drainage_type={integer}
&surface_drainage_quality={integer}&irrigation_type={integer}

2.1.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

latitude

float

yes

Latitude coordinate near the center of the field in decimal degrees.

longitude

float

yes

Longitude coordinate near the center of the field in decimal degrees.

acres

float

yes

Areal size of the field in acres.

name

string

no

Name of the field. Default is “unnamed field.”

type

integer

no

Enumeration value representing field type.

subtype

integer

no

Enumeration value representing field sub-type.

surface_drainage_quality

integer

no

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average (default), and 2 is good.

subsurface_drainage_type

integer

no

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

irrigation_type

integer

no

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” (default) and 1 is “true.”

2.1.3. Response Object

A string representing a new field ID.

2.1.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/create?
app_id=123&app_key=321&account_id=123&user_id=xyz-123
&latitude=45&longitude=-100&acres=100

2.1.5. Example Response

321-abc

2.2. Modify Field - v1.0

The Modify Field endpoint allows users to change various properties of any created field contained in the user information database. Users may update field name, latitude-longitude coordinates, acreage, drainage type and quality, irrigation type, and field type and subtype.

2.2.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/modify/{field_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&latitude={float}&longitude={float}&acres={float}&name={string}
&type={integer}&subtype={integer}&subsurface_drainage_type={integer}
&surface_drainage_quality={integer}&irrigation_type={integer}

2.2.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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_id

string

yes

Specifies ID of field to be modified, provided by the Create Field endpoint.

type

integer

no

Enumeration value representing field type.

name

string

no

New name of the field.

latitude

float

no

Updated latitude coordinate near the center of the field.

longitude

float

no

Updated longitude coordinate near the center of the field.

subtype

integer

no

Enumeration value representing field sub-type.

acres

float

no

Updated areal size of the field in acres.

surface_drainage_quality

integer

no

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

subsurface_drainage_type

integer

no

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” and 1 is “true.”

irrigation_type

integer

no

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

2.2.3. Response Object

A string representing success (“true”) or failure (“false”).

2.2.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/modify/321-abc?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

2.2.5. Example Response

true

2.3. Delete Field - v1.0

The Delete Field endpoint allows users to remove a specific field and associated field information attributed to their account ID and user ID.

2.3.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/delete/{field_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

2.3.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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_id

string

yes

Specifies a comma-delimited list of IDs of fields to be deleted from the database.

2.3.3. Response Object

A string representing success (“true”) or failure (“false”).

2.3.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/delete/321-abc?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

2.3.5. Example Response

true

2.4. Get Field Information - v1.0

This endpoint allows users to pull information related to a specific field ID. The information available ranges from field size and location to irrigation and drainage details.

2.4.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/info/{field_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

2.4.2. 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

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_id

string

yes

Specifies a comma-delimited list of IDs of fields to be queried from the user information database.

2.4.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds2.

field_id

Specifies ID of the field queried.

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

name

Name of the field.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” and 1 is “true.”

type

Enumeration value representing field type.

subtype

Enumeration value representing field sub-type.

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.4.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/info/321-abc?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

2.4.5. Example Response

[
    {
        "acres":"600.0",
        "created": 1420070400,
        "field_id":"321-abc",
        "irrigation_type":1,
        "latitude":45.0,
        "longitude":-100.0,
        "name":"Bob’s Field",
        "subdrainage_type":1,
        "subtype":1,
        "surface_drainage_quality":2,
        "type":1
    }
]

3. Field Activity

Once a field has been added to Iteris’ user information database, users can enter and manage activity done to the field using the Add Field Activity, Modify Field Activity, Delete Field Activity, Get Field Activity by Activity ID, and Get Field Activity by Field ID endpoints. The system should be notified when certain activities, such as cultivating, are performed on a field. This information will help improve results.

3.1. Add Field Activity - v1.0

The Add Field Activity endpoint allows for information to be added to the system that is specific to the work being done on a given field. The type of field activities that can be added to the endpoint include planting, spraying, and harvesting.

3.1.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/activity/add/{field_id}/
{activity_type}?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&activity_time={timestamp}&subtype={integer}

3.1.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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_id

string

yes

Specifies ID of the field to which the new field activity is to be associated.

activity_type

integer

yes

Code representing the kind of activity that was done on the field, such as planting, spraying, and harvesting. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

subtype

integer

no

Code representing the variation of the type of activity done on the field, such as the type of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

activity_time

timestamp

no

Approximate time at which the field activity occurred.

3.1.3. Response Object

A string representing a new activity ID.

3.1.4. Example Request

http://ag.us.clearapis.com//v1.0/accounts/field/activity/add/123-456/311?
app_id=123&app_key=321&account_id=123&user_id=xyz-123&subtype=99
&activity_time=1416699304&data=0.25in

3.1.5. Example Response

123-456

3.2. Modify Field Activity - v1.0

The Modify Field Activity endpoint allows users to update several properties associated with a specific field activity contained in the user information database. These properties include the type and subtype of activity performed, and the approximate time at which it was performed.

3.2.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/activity/modify/{activity_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&subtype={integer}&activity_time={timestamp}

3.2.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

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

activity_id

string

yes

Specifies ID of the field activity to be modified in the user information database and is provided by the Add Field Activity endpoint as a result of adding a new activity to the database.

subtype

integer

no

Code representing the variation of the type of activity done on the field, such as the type of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

activity_time

timestamp

no

Updated approximate time at which field activity occurred.

3.2.3. Response Object

A string representing success (“true”) or failure (“false”).

3.2.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/activity/modify/123-456?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

3.2.5. Example Response

true

3.3. Delete Field Activity - v1.0

Users have the option of deleting previously entered field activity details by using the Delete Field Activity endpoint.

3.3.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/activity/delete/{activity_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

3.3.2. 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

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.

activity_id

string

yes

Specifies ID of the field activity to be deleted from the user information database and is provided by the Add Field Activity endpoint as a result of adding a new activity to the database.

3.3.3. Response Object

A string representing success (“true”) or failure (“false”).

3.3.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/activity/delete/123-456?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

3.3.5. Example Response

true

3.4. Get Field Activity By Activity ID - v1.0

This endpoint allows for users to gather a list of fields that share a common activity, such as the date in which a specific crop was planted.

3.4.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/activity/info/{activity_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

3.4.2. 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

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.

activity_id

string

yes

Specifies ID of the field activity queried in the user information database and is provided by the Add Field Activity endpoint as a result of adding a new activity to the database.

3.4.3. Response Object (JSON)

Field Description

activity_time

Approximate time at which field activity occurred, given as a timestamp.

subtype

Code representing the kind of activity that was done on the field, such as planting, spraying, and harvesting. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

activity_type

Code representing the variation of the type of activity done on the field, such as the type of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

created

Epoch timestamp in seconds representing the time an activity was initially stored2.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.4.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/activity/info/123-456?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

3.4.5. Example Response

{
    "activity_time":1416699304,
    "activity_type":1,
    "created":1438974059,
    "data":"0.25 in",
    "subtype":99
}

3.5. Get Field Activity By Field ID - v1.0

The Get Field Activity By Field ID endpoint returns all field activity entered for a specific field in the user information database, including the types of activities performed and the approximate times.

3.5.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/activity/info/by_field/{field_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

3.5.2. 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

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_id

string

yes

Specifies ID of the field queried.

3.5.3. Response Object (JSON)

Field Description

activity_time

Approximate time at which field activity occurred, given as a timestamp.

subtype

Code representing the kind of activity that was done on the field, such as planting, spraying, and harvesting. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

activity_type

Code representing the variation of the type of activity done on the field, such as the type of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

created

Epoch timestamp in seconds representing the time an activity was initially stored2.

field_activity_id

Specifies ID of the given field activity.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.5.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/activity/info/by_field/321-abc?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

3.5.5. Example Response

[
    {
        "activity_time":1416699304,
        "activity_type":311,
        "created":1438714537,
        "data":”0.75 in",
        "field_activity_id":"dc3d3219-483d-4a0f-b188-ae6cee36d8b8",
        "subtype":99
    },
    {
        "activity_time":1416699304,
        "activity_type":311,
        "created":1438713436,
        "data":"0.25 in",
        "field_activity_id":"d8ed0f65-b5b3-440d-8127-c8ffc18d9229",
        "subtype":99
    }
]

3.6. 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.

3.6.1. URL Description

http://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}

3.6.2. Request Parameters

Parameter Type Required Description

model

integer

yes

The model_id returned by the field accessibility advisory service.

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 applies2.

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.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.6.3. Response Object (JSON)

A string representing a feedback ID.

3.6.4. Example Request

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

3.6.5. Example Response

def-345

4. Field Users

In order to utilize many field and growth-related API functions, a user must have appropriate privileges. The following endpoints assist users in managing these privileges.

4.1. Register Field User - v1.0

For a user within an account to utilize field-related and growth-related activities they must have the appropriate privileges. This endpoint creates read or write privileges for a user for a target field.

4.1.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/users/add/{field_id}/{target_user_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&privilege={string}

4.1.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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.

target_user_id

string

yes

User ID for user to be given privileges.

field_id

string

yes

Unique ID of field for which to grant privileges.

privilege

string

no

Specifies privilege level to be granted. Valid values: “read” (default) and “write.”

4.1.3. Response Object

A string representing success (“true”) or failure (“false”).

4.1.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/users/add/321-abc/xyz-123?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

4.1.5. Example Response

true

4.2. Modify Field User - v1.0

The Modify Field User endpoint allows for a user’s privileges to be edited as needed.

4.2.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/users/modify/{field_id}/
{target_user_id}?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&privilege={string}

4.2.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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.

target_user_id

string

yes

Target user’s unique ID.

field_id

string

yes

Unique ID of field for which to grant privileges.

privilege

string

no

Privilege level to be set for target user and field. Valid values: “read” (default) and “write.”

4.2.3. Response Object

A string representing success (“true”) or failure (“false”).

4.2.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/users/modify/321-abc/xyz-123?
app_id=123&app_key=321&account_id=123&user_id=xyz-123&privilege=write

4.2.5. Example Response

true

4.3. Remove Field User - v1.0

Privileges to perform operations or view content for a given field can be revoked through the Remove Field User endpoint.

4.3.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/field/users/delete/{field_id}/
{target_user_id}?app_id={string}&app_key={string}&account_id={string}
&user_id={string}

4.3.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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_id

string

yes

Unique field ID for which to remove a user’s privileges.

target_user_id

string

yes

Unique ID of user for which to revoke all privileges.

4.3.3. Response Object

A string representing success (“true”) or failure (“false”).

4.3.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/field/users/delete/321-abc/xyz-123?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

4.3.5. Example Response

true

5. Growth

By providing information specific to existing crops, users are able to take advantage of various crop-specific advisements. The following endpoints are to be used for providing, viewing, and modifying the necessary information to take advantage of these systems.

5.1. Create Growth - v1.0

This endpoint is to be used to record that a crop is growing on an existing field. Various crop properties required for growth predictions and advisements are required.

5.1.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/growth/create/{field_id}/{plant_type}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&plant_date={timestamp}&seed_variety={string}&plant_subtype={integer}
&relative_maturity={string}&name={string}

5.1.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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_id

string

yes

Specifies ID of field to which to assign crop growth data.

plant_type

integer

yes

Enumeration value representing the type of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

seed_variety

string

no

Additional description or notes for the seed used.

plant_subtype

integer

no

Enumeration value representing the specific variety of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

relative_maturity

string

no

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

plant_date

timestamp

no

Approximate time at which the crop was planted.

name

string

no

User may name this growth if desired.

5.1.3. Response Object

A string representing a new growth ID.

5.1.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/growth/create/321-abc/0?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

5.1.5. Example Response

abc-def

5.2. Modify Growth - v1.0

Existing growth properties can be modified through the use of this endpoint. This endpoint allows users to update information such as the planting date and relative maturity of a particular crop planted, in addition to several other properties.

5.2.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/growth/modify/{growth_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&name={string}&harvest_date={timestamp}&plant_date={timestamp}
&plant_type={integer}&plant_subtype={integer}&seed_variety={string}
&relative_maturity={string}

5.2.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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.

growth_id

string

yes

Specifies ID of crop growth to be modified, provided by the Create Growth endpoint.

name

string

no

New name of the field.

harvest_date

timestamp

no

An epoch timestamp in seconds for which harvest has begun2.

plant_date

timestamp

no

Updated approximate time at which the crop was planted.

plant_type

integer

no

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

integer

no

Coded value representing the specific variety of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

seed_variety

string

no

Additional description or notes for the seed used.

relative_maturity

string

no

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5.2.3. Response Object

A string representing success (“true”) or failure (“false”).

5.2.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/growth/modify/abc-def?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

5.2.5. Example Response

true

5.3. Delete Growth - v1.0

Growths currently assigned to a field can be removed by utilizing this endpoint. Various information useful for machine learning processes, such as growth feedback provided through the Crop Health API endpoints, will remain.

5.3.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/growth/delete/{growth_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

5.3.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

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

growth_id

string

yes

Specifies ID of crop growth to be deleted from the user information database, provided by the Create Growth endpoint.

5.3.3. Response Object

A string representing success (“true”) or failure (“false”).

5.3.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/growth/delete/abc-def?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

5.3.5. Example Response

true

5.4. Get Growth Information - v1.0

Information regarding a specific crop can be gathered from Iteris’ user information database by providing the appropriate account, user, and growth IDs to the Get Growth Information endpoint. This endpoint provides a variety of information about the crop, including field-specific properties. These properties can include the ID of the field in which the crop has been planted; the latitude and longitude coordinates; the drainage quality; and growth-specific properties such as the type of crop planted, its planting date, and the relative maturity value.

5.4.1. URL Description

http://ag.us.clearapis.com/v1.0/accounts/growth/info/{growth_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

5.4.2. Request Parameters

Parameter Type Required Definition

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your 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.

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5.4.3. Response Object

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds2.

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun2.

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5.4.4. Example Request

http://ag.us.clearapis.com/v1.0/accounts/growth/info/abc-def?
app_id=123&app_key=321&account_id=123&user_id=xyz-123

5.4.5. Example Response

[
    {
        "acres":600.0,
        "created":1420827616,
        "data":null,
        "field_id":"321-abc",
        "field_name":"Bob’s Field",
        "growth_id":"abc-def",
        "harvest_date":null,
        "irrigation_type":1,
        "latitude":45.0,
        "longitude":-100.0,
        "name":"quadrant 1-3",
        "plant_date":1402790400,
        "plant_name":"barley",
        "plant_properties":"{\"name\":\"barley\"}",
        "plant_subtype":null,
        "plant_type":null,
        "relative_maturity":"0",
        "seed_variety":"n/a",
        "subdrainage_type":1,
        "surface_drainage_quality":2
    }
}

Appendix

Appendix A: Supplementary API Information

A.1. 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.

A.2. 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.

A.3. Epoch/Unix Timestamp

Iteris employs Epoch/Unix timestamps for time-based parameters. This system works by defining situations in time by the number of seconds since 1970-01-01 00:00 Coordinated Universal Time (UTC).

A.4. Activity and Plant Codes

A.4.1. Activity Type

Coded Value Meaning

300

Planting

301

Spraying

302

Harvesting

303

Row Crop Cultivating

304

Post-harvest Tillage

305

Pre-planting Tillage

306

Cutting

307

Soil Test

308

Fertilizer Treatment

309

Grain Moisture Test

310

Scouting Report

311

Irrigation

A.4.2. Activity Subtype

Activity Type Subtype Code Meaning

Planting

0

Generic

Planting

50

Barley

Planting

51

Corn

Planting

57

Spring Wheat

Planting

59

Canola

Planting

60

Sugar Beets

Planting

65

Cotton

Spraying

0

Generic

Harvesting

0

Generic

Row Crop Cultivating

0

Generic

Post-harvest Tillage

0

Generic

Pre-planting Tillage

0

Generic

Cutting

0

Generic

Cutting

1

Alfalfa

Soil Test

0

Generic

Fertilizer Treatment

0

Generic

Grain Moisture Test

0

Generic

Scouting Report

0

Generic

Irrigation

0

Generic

A.4.3. Plant Type

Coded Value Meaning

50

barley

51

corn

57

springwheat

59

canola

60

sugarbeet

65

cotton

66

soybean

68

winter wheat

70

sorghum

72

sunflower

A.4.4. Plant Subtype

Plant Type Subtype Code Meaning

Barley

0

Generic

Corn

0

Generic

Sugar Beet

0

Generic

Canola

0

Generic

Spring Wheat

0

Generic

Cotton

0

Generic

Soybean

0

Generic

A.4.5. Crop-specific Relative Maturity

Crop Description

Corn

Must be an integer between 70 and 130. Lower numerical values represent “early” relative maturity, resulting in plants maturing fast. A higher numerical value represents crops that have a “late” relative maturity, meaning a relatively slow maturity. If no value is provided, the default relative maturity is 100.

Spring Wheat

Valid values include “early,” “medium,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly.

Winter Wheat

Valid values include “early,” “medium,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly.

Cotton

Categorized by one of the following statements: “early,” “medium-early,” “medium,” “medium-late,” or “late.” If no value is given, a default relative maturity of “medium” will be used.

Soybean

Currently, the ClearAg models allow for the soybean maturity group to be from 2 to 4.5, with a lower number indicating earlier maturity and a higher number indicating later maturity. If no value is provided, the default maturity group is 3.0.