https://ag.us.clearapis.com/v1.0/accounts/user/create?app_id={string}
&app_key={string}&account_id={string}&name={string}&email={string}
last updated 11/7/18
Welcome to the Iteris ClearAg Accounts API. This system allows users to create and utilize a tightly integrated interface of ClearAg APIs featuring several field/growth-specific capabilities, including growth models, irrigation, nutrient, and harvest drydown services.
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.
The ClearAg Accounts API is used to create, add, modify, and delete individual users and the field(s) associated with each user. This is the primary mechanism that enables ClearAg’s field and crop-specific agronomic API services to track and record the state of the crop and benefit from user input and feedback. Having a field ID created by the Accounts API is the first step in using many of the Crop Health API endpoints, including the growth, nutrient, and drydown models, as well as custom soil modeling and irrigation recommendation services.
Note that while at least one user ID must be established in order to create and manage one or more fields, it is not necessary from a technical perspective to create individual accounts for each end user of an application that uses the ClearAg APIs, nor is it necessary that user accounts include any kind of personally identifiable information (PII). It is the responsibility of the authorized API user to implement the use of the Accounts API in such a manner that complies with any applicable PII laws or regulations to which their business is subject.
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. Additionally, the ClearAg Customer Success Team can provide best practice recommendations on integrating the Account API for your particular use case.
Please note that API responses are currently only provided in English.
Iteris requires the use of https when working within the ClearAg APIs.
Additional API information, such as details on supported unit sets and API behavior, is available in the Appendix.
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.
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.
https://ag.us.clearapis.com/v1.0/accounts/user/create?app_id={string}
&app_key={string}&account_id={string}&name={string}&email={string}
| 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. |
string |
no |
New user’s email address. |
A string representing a new user ID.
https://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
xyz-123
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.
https://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}
| 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. |
string |
no |
The email address of the user. The user must supply at least one of the "name" or "email" parameters in the URL. |
A string representing success ("true") or failure ("false").
https://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
true
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.
https://ag.us.clearapis.com/v1.0/accounts/user/delete/{target_user_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
| 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. |
A string representing success ("true") or failure ("false").
https://ag.us.clearapis.com/v1.0/accounts/user/delete/xyz-123? app_id=123&app_key=321&account_id=123&user_id=xyz-123
true
The Get User Information endpoint functions as a medium to obtain information on users registered to an account.
https://ag.us.clearapis.com/v1.0/accounts/user/info/{target_user_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
| 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. |
| Field | Description |
|---|---|
account_id |
A unique account ID provided by an Iteris account representative. |
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. |
https://ag.us.clearapis.com/v1.0/accounts/user/info/xyz-123? app_id=123&app_key=321&account_id=123&user_id=xyz-123
{
"account_id":"123",
"email":"joesmith@jsmith.com",
"name":"Joe Smith",
"user_id":"xyz-123"
}
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.
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.
https://ag.us.clearapis.com/v1.0/accounts/field/create?app_id=
{string}&app_key={string}&account_id={string}&field_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}&texture_classes={string}
&texture_depth_unit={string}
| 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. |
field_id |
string |
no |
A custom field id may be chosen for easier integration. This value must be a valid UUID, with or without hyphens. Example: 'd992cb75-7446-42c1-a541-a0e73712141b' or '8efdbb3e0bf041f7-925b488deca6a032.' If an already existing field id is provided for the same account, an error will be returned. |
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. Please verify that latitude/longitude coordinates are over soil representative of your field. |
longitude |
float |
yes |
Longitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. |
acres |
float |
yes |
Areal size of the field in acres. |
name |
string |
no |
This parameter can be used as an associated field name for keeping track of fields, or for creating a user-specific field tracking convention. The 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." |
texture_classes |
string |
no |
A list of tuples where the tuples contain pairs of depth (float), texture_class_id (integer). If this is present, soil depth 0 must be included and duplicates depths are not allowed. Must be present if texture_depth_unit is provided. Setting this to null results in the default texture class for this location. Addition information can be found in the USDA Texture Classes section of the Appendix. |
texture_depth_unit |
string |
no |
The measurement unit ('in' or 'cm') pertaining to the depths of texture_classes. Please note that if inches are used, they will be converted and stored as centimeters. Must be present if texture_classes is provided. |
A string representing a new field ID.
https://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&texture_depth_unit=cm &texture_classes=[(0,2),(20,2),(40,9)]
321-abc
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.
https://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}
&texture_classes={string}&texture_depth_unit={string}
| 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. Please verify that latitude/longitude coordinates are over soil representative of your field. |
longitude |
float |
no |
Updated longitude coordinate near the center of the field. Please verify that latitude/longitude coordinates are over soil representative of your 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." |
texture_classes |
string |
no |
A list of tuples where the tuples contain pairs of depth (float), texture_class_id (integer). If this is present, soil depth 0 must be included and duplicates depths are not allowed. Must be present if texture_depth_unit is provided. Setting this to null will revert the value to the default. Addition information can be found in the USDA Texture Classes section of the Appendix. |
texture_depth_unit |
string |
no |
The measurement unit ('in' or 'cm') pertaining to the depths of texture_classes. Please note that if inches are used, they will be converted and stored as centimeters. Must be present if texture_classes is provided. |
A string representing success ("true") or failure ("false").
https://ag.us.clearapis.com/v1.0/accounts/field/modify/321-abc? app_id=123&app_key=321&account_id=123&user_id=xyz-123
true
The Delete Field endpoint allows users to remove a specific field and associated field information attributed to their account ID and user ID.
https://ag.us.clearapis.com/v1.0/accounts/field/delete/{field_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
| 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. |
A string representing success ("true") or failure ("false").
https://ag.us.clearapis.com/v1.0/accounts/field/delete/321-abc? app_id=123&app_key=321&account_id=123&user_id=xyz-123
true
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.
https://ag.us.clearapis.com/v1.0/accounts/field/info/{field_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
| 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. |
| Field | Description |
|---|---|
acres |
Areal size of the field in acres. |
created |
Epoch timestamp in seconds. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp. |
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. Please verify that latitude/longitude coordinates are over soil representative of your field. |
longitude |
Longitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. |
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. |
https://ag.us.clearapis.com/v1.0/accounts/field/info/321-abc? app_id=123&app_key=321&account_id=123&user_id=xyz-123
[
{
"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
}
]
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.
https://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}
| 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. |
| 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 stored. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp. |
field_activity_id |
Specifies ID of the given field activity. |
https://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
[
{
"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
}
]
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.
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.
https://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}
| 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." |
A string representing success ("true") or failure ("false").
https://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
true
The Modify Field User endpoint allows for a user’s privileges to be edited as needed.
https://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}
| 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." |
A string representing success ("true") or failure ("false").
https://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
true
Privileges to perform operations or view content for a given field can be revoked through the Remove Field User endpoint.
https://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}
| 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. |
A string representing success ("true") or failure ("false").
https://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
true
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.
In some cases values will be represented as "n/a." This indicates that the requested data is not available or is not applicable.
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).
| 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 |
| 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 |
| texture class | texture class description |
|---|---|
1 |
Sand |
2 |
Loamy Sand |
3 |
Sandy Loam |
4 |
Silt Loam |
5 |
Silt |
6 |
Loam |
7 |
Sandy Clay Loam |
8 |
Silty Clay Loam |
9 |
Clay Loam |
10 |
Sandy Clay |
11 |
Silty Clay |
12 |
Clay |
13 |
Organic Materials |
14 |
Water |
15 |
Bedrock |
16 |
Other |
This section describes document changes occurring in the two most recent versions.