Accounts API

last updated 9/17/20

Welcome to the 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 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.

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

The use of HTTPS are required when working within the ClearAg APIs.

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

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.

Create User - v1.0

After first obtaining an account ID provided by DTN, 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.

URL Description

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

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your account representative.
name	string	no	New user’s name.
email	string	no	New user’s email address.

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

A unique account ID provided by your account representative.

name

string

New user’s name.

string

New user’s email address.

Response Object

A string representing a new user ID.

Example Request

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

Example Response

xyz-123

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.

URL Description

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}

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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.

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

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

string

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

Response Object

Returns "true" on success.

Example Request

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

Example Response

true

Remove User - v1.0

The Remove User endpoint allows for the deletion of a user from the 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.

URL Description

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}

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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.

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

Response Object

Returns "true" on success.

Example Request

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

Example Response

true

Get User Information - v1.0

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

URL Description

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}

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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.

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

Response Object (JSON)

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

Field

Description

account_id

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

Example Request

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

Example Response

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

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 DTN models to process events.

Create Field - v1.0

The Create Field endpoint serves as a means of entering a new field into the 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.

URL Description

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}&texture_classes={string}&texture_depth_unit={string}

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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 the given 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 the given 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."
texture_classes	string	no	The depth of the layer is defined by the top of each user provided layer. If there is only one layer, set the top of the layer to 0 and the API will count it for the whole depth. For multiple layers, only the top of the depth layer is needed. For example: with a multi-texture class of sand and clay, the top layer of sand input would be (0,1). The clay layer 5 cm down would have an input of (5,12). The resulting request would be: [(0,1),(5,12)]. 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.

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

A unique account ID provided by your account representative.

field_id

string

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 the given 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 the given field.

acres

float

yes

Areal size of the field in acres.

name

string

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

texture_classes

string

The depth of the layer is defined by the top of each user provided layer. If there is only one layer, set the top of the layer to 0 and the API will count it for the whole depth. For multiple layers, only the top of the depth layer is needed. For example: with a multi-texture class of sand and clay, the top layer of sand input would be (0,1). The clay layer 5 cm down would have an input of (5,12). The resulting request would be: [(0,1),(5,12)]. Addition information can be found in the USDA Texture Classes section of the Appendix.

texture_depth_unit

string

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.

Response Object

A string representing a new field ID.

Example Request

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)]

Example Response

321-abc

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.

URL Description

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}&texture_classes={string}&texture_depth_unit={string}

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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.
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 the given field.
longitude	float	no	Updated longitude coordinate near the center of the field. Please verify that latitude/longitude coordinates are over soil representative of the given field.
acres	float	no	Updated areal size of the field in acres.
texture_classes	string	no	The depth of the layer is defined by the top of each user provided layer. If there is only one layer, set the top of the layer to zero and the API will count it for the whole depth. For multiple layers, only the top of the depth layer is needed. For example: with a multi-texture class of sand and clay, the top layer of sand input would be (0,1). The clay layer five cm down would have an input of (5,12). The resulting request would be: [(0,1),(5,12)]. 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.

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

name

string

New name of the field.

latitude

float

Updated latitude coordinate near the center of the field. Please verify that latitude/longitude coordinates are over soil representative of the given field.

longitude

float

Updated longitude coordinate near the center of the field. Please verify that latitude/longitude coordinates are over soil representative of the given field.

acres

float

Updated areal size of the field in acres.

texture_classes

string

The depth of the layer is defined by the top of each user provided layer. If there is only one layer, set the top of the layer to zero and the API will count it for the whole depth. For multiple layers, only the top of the depth layer is needed. For example: with a multi-texture class of sand and clay, the top layer of sand input would be (0,1). The clay layer five cm down would have an input of (5,12). The resulting request would be: [(0,1),(5,12)]. Addition information can be found in the USDA Texture Classes section of the Appendix.

texture_depth_unit

string

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.

Response Object

Returns "true" on success.

Example Request

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

Example Response

true

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.

URL Description

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

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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 maximum of 100 field IDs allowed.

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

A unique account ID provided by your 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 maximum of 100 field IDs allowed.

Response Object

Returns "true" on success.

Example Request

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

Example Response

true

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.

URL Description

https://ag.us.clearapis.com/v1.0/accounts/field/info/{field_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 DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

Response Object (JSON)

Field	Description
acres	Areal size of the field in acres.
created	Field creation time in the form of a Unix timestamp.
field_id	Specifies ID of the field queried.
irrigation_type	Represents whether or not the cropland utilizes pivot irrigation. Valid values: zero is "false" and one is "true." ^*This variable has been deprecated.
latitude	Latitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of the given field.
longitude	Longitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of the given field.
name	Name of the field.
subdrainage_type	Represents whether or not the cropland utilizes drainage tile. Valid values: zero is "false" and one is "true."
surface_drainage_quality	Represents field drainage effectiveness. Valid values: zero is poor, one is average, and two is good.
type	Enumeration value representing field type.
subtype	Enumeration value representing field sub-type.

Field

Description

acres

Areal size of the field in acres.

created

Field creation time in the form of a Unix timestamp.

field_id

Specifies ID of the field queried.

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: zero is "false" and one is "true." ^*This variable has been deprecated.

latitude

Latitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of the given field.

longitude

Longitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of the given field.

name

Name of the field.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: zero is "false" and one is "true."

surface_drainage_quality

Represents field drainage effectiveness. Valid values: zero is poor, one is average, and two is good.

type

Enumeration value representing field type.

subtype

Enumeration value representing field sub-type.

Example Request

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

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
    }
]

Field Activity

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.

URL Description

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}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

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	Field creation time in the form of a Unix timestamp.
field_activity_id	Specifies ID of the given field activity.

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

Field creation time in the form of a Unix timestamp.

field_activity_id

Specifies ID of the given field activity.

Example Request

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

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
    }
]

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.

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.

URL Description

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}

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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."

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

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

Response Object

Returns "true" on success.

Example Request

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

Example Response

true

Modify Field User - v1.0

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

URL Description

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}

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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."

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

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

Response Object

Returns "true" on success.

Example Request

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

Example Response

true

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.

URL Description

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}

Request Parameters

Parameter	Type	Required	Definition
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your 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.

Parameter

Type

Required

Definition

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

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

Response Object

Returns "true" on success.

Example Request

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

Example Response

true

Field Observation

Add Field Observation

This endpoint allows for the addition of field observations. Please note that currently the Field Observation information only affects ClearAg Focus Soil Conditions and IMFocus results (i.e. Custom Field Modeling based products). This information does not impact precipitation inputs into products such as Harvest, Nutrient, Spray Window, and Field Accessibility.

URL Description

Using query string credentials

curl -X POST \
'https://ag.us.clearapis.com/v1.0/field/observation/add?account_id=abc-123&user_id=def-456&field_id=ghi-789&app_id=abc-123&app_key=123-abc' \
  -H 'Content-Type: application/json' \
  -d '{
    "observations":[
        {
            "precip_acc":40,
            "start_time":1546344000,
            "precip_acc_unit":"mm",
            "name":"Station 1",
            "end_time":1546358399
        },
        {
            "precip_acc":0.709,
            "start_time":1546358400,
            "precip_acc_unit":"in",
            "end_time":1546372799
        }
    ]
}'

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
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	Target field ID for observations to be applied. User must have write privileges on field. Can be provided in query string or form data.
observations	JSON object	yes	List of JSON objects containing the data of each individual observation. There is a maximum of 50 observations allowed per call.
observations: precip_acc	float	yes	The amount of precipitation accumulated between the start_time and end_time.
observations: precip_acc_unit	string	yes	The unit associated with the precipitation accumulated value. Valid units are "in" or "mm."
observations: start_time	timestamp	yes	Unix timestamp in seconds representing the time the observation was started. Please note that there are minimum and maximum timespans between start_time and end_time of one hour and 24 hours respectively.
observations: end_time	timestamp	yes	Unix timestamp in seconds representing the time an observation ended. Please note that there are minimum and maximum timespans between start_time and end_time of one hour and 24 hours respectively.
observations: name	string	no	A name can be provided.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

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

Target field ID for observations to be applied. User must have write privileges on field. Can be provided in query string or form data.

observations

JSON object

yes

List of JSON objects containing the data of each individual observation. There is a maximum of 50 observations allowed per call.

observations: precip_acc

float

yes

The amount of precipitation accumulated between the start_time and end_time.

observations: precip_acc_unit

string

yes

The unit associated with the precipitation accumulated value. Valid units are "in" or "mm."

observations: start_time

timestamp

yes

Unix timestamp in seconds representing the time the observation was started. Please note that there are minimum and maximum timespans between start_time and end_time of one hour and 24 hours respectively.

observations: end_time

timestamp

yes

Unix timestamp in seconds representing the time an observation ended. Please note that there are minimum and maximum timespans between start_time and end_time of one hour and 24 hours respectively.

observations: name

string

A name can be provided.

JSON Example Response

[
    "321-456",
    "456-789"
]

Get Field Observation

This endpoint allows for the retrieval of field observations by either a time range or a list of observation_id’s. Please note that currently the Field Observation information only affects ClearAg Focus Soil Conditions and IMFocus results (i.e. Custom Field Modeling based products). This information does not impact precipitation inputs into products such as Harvest, Nutrient, Spray Window, and Field Accessibility.

URL Description

https://ag.us.clearapis.com/v1.0/field/observation/get?app_id={string}&app_key={string}&account_id={string}&user_id={string}&field_id={string}&start_time={integer}&end_time={integer}&unitcode={string}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	Your Accounts API account ID.
user_id	string	yes	User ID provided by and used with the Accounts API. Calling user is required to have at least read permissions for target field ID.
field_id	string	yes	Target field ID for which to retrieve observations.
observation_ids	string	no	Comma delimited list of target observation UUID’s. Cannot be provided in conjunction with "start_time" or "end_time." If provided, list length is limited to 50.
start_time	integer	no	Unix timestamp for start of range selection. Note: only observations for which start_time is within time range selection will be returned. Requires that "end_time" also be provided. Cannot be provided in conjunction with "observation_id’s." There is a limit of 31 days between start_time and end_time. If neither observation_ids or start_time/end_time are provided, the call is defaulted to pulling the first 50 observations starting with the earliest start_time in ascending order.
end_time	integer	no	Unix timestamp for end of range selection. Requires that "start_time" also be provided. Cannot be provided in conjunction with "observation_id’s." If neither observation_ids or start_time/end_time are provided, the call is defaulted to pulling the first 50 observations starting with the earliest start_time in ascending order.
unitcode	string	no	Standard system of measurement for which to return values. Valid values are "us-std" or "si-std." Default of "us-std."

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. Calling user is required to have at least read permissions for target field ID.

field_id

string

yes

Target field ID for which to retrieve observations.

observation_ids

string

Comma delimited list of target observation UUID’s. Cannot be provided in conjunction with "start_time" or "end_time." If provided, list length is limited to 50.

start_time

integer

Unix timestamp for start of range selection. Note: only observations for which start_time is within time range selection will be returned. Requires that "end_time" also be provided. Cannot be provided in conjunction with "observation_id’s." There is a limit of 31 days between start_time and end_time. If neither observation_ids or start_time/end_time are provided, the call is defaulted to pulling the first 50 observations starting with the earliest start_time in ascending order.

end_time

integer

Unix timestamp for end of range selection. Requires that "start_time" also be provided. Cannot be provided in conjunction with "observation_id’s." If neither observation_ids or start_time/end_time are provided, the call is defaulted to pulling the first 50 observations starting with the earliest start_time in ascending order.

unitcode

string

Standard system of measurement for which to return values. Valid values are "us-std" or "si-std." Default of "us-std."

Response Object (JSON)

Field	Description
units: precip_acc	Unit of measurement for precip_acc parameters.
observations: precip_acc	The amount of measured precipitation accumulated between the start_time and end_time.
observations: start_time	Unix timestamp in seconds representing the time start of observation.
observations: end_time	Unix timestamp in seconds representing end of observation period.
observations: name	Name of observation if one was provided, otherwise a "null" value.

Field

Description

units: precip_acc

Unit of measurement for precip_acc parameters.

observations: precip_acc

The amount of measured precipitation accumulated between the start_time and end_time.

observations: start_time

Unix timestamp in seconds representing the time start of observation.

observations: end_time

Unix timestamp in seconds representing end of observation period.

observations: name

Name of observation if one was provided, otherwise a "null" value.

Example Request

https://ag.us.clearapis.com/v1.0/field/observation/get?app_id=123&app_key=321&account_id=abc-123&user_id=def-456&field_id=ghi-789&start_time=1546300800&end_time=1546905600&unitcode=us-std

Example Response

{
	"units":{
		"precip_acc":"mm"
	},
	"observations":[{
			"observation_id":"321-456",
			"start":1546344000,
			"end":1546358399,
			"name":"Station 1",
			"precip_acc":40
		},
		{
			"observation_id":"456-789",
			"start":1546358400,
			"end":1546372799,
			"name":null,
			"precip_acc":18
		}
	]
}

Delete Field Observation

This endpoint allows for the deletion of field observations by either a time range or a list of observation_id’s. Please note that currently the Field Observation information only affects ClearAg Focus Soil Conditions and IMFocus results (i.e. Custom Field Modeling based products). This information does not impact precipitation inputs into products such as Harvest, Nutrient, Spray Window, and Field Accessibility.

URL Description

https://ag.us.clearapis.com/v1.0/field/observation/delete?app_id={string}&app_key={string}&account_id={string}&user_id={string}&field_id={string}&start_time={integer}&end_time={integer}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	Your Accounts API account ID.
user_id	string	yes	User ID provided by and used with the Accounts API. Calling user must have write privileges for the target field.
field_id	string	yes	Target field ID for which observations are to be deleted.
observation_ids	string	no	Comma delimited list of observation ID’s which to delete. Cannot be provided in conjunction with "start_time" or "end_time." There is a limit of 50 observation_ids per deletion attempt.
start_time	integer	no	Unix timestamp in seconds for start of range selection. Requires that "end_time" also be provided. Cannot be provided in conjunction with "observation_id’s." There is a limit of 31 days between start_time and end_time. Observations are selected if their observation start time is contained within the specified time range.
end_time	integer	no	Unix timestamp in seconds for end of range selection. Requires that "start_time" also be provided. Cannot be provided in conjunction with "observation_id’s." There is a limit of 31 days between start_time and end_time.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. Calling user must have write privileges for the target field.

field_id

string

yes

Target field ID for which observations are to be deleted.

observation_ids

string

Comma delimited list of observation ID’s which to delete. Cannot be provided in conjunction with "start_time" or "end_time." There is a limit of 50 observation_ids per deletion attempt.

start_time

integer

Unix timestamp in seconds for start of range selection. Requires that "end_time" also be provided. Cannot be provided in conjunction with "observation_id’s." There is a limit of 31 days between start_time and end_time. Observations are selected if their observation start time is contained within the specified time range.

end_time

integer

Unix timestamp in seconds for end of range selection. Requires that "start_time" also be provided. Cannot be provided in conjunction with "observation_id’s." There is a limit of 31 days between start_time and end_time.

Response Object

Returns "true" on success.

Example Request

https://ag.us.clearapis.com/v1.0/field/observation/delete?app_id=abc-123&app_key=def-456&account_id=ghi-789&user_id=jkl-101&field_id=mno-121&start_time=1546300800&end_time=1547510400

Example Response

true

Zone Management

Create Field Zone Map - 1.0

This endpoint allows a user to create a field zone map by uploading a shapefile or GeoJSON file. Additional details specific to file type are provided below, under the File Type header. Please note that output information will be different based upon user-provided parameters and format.

URL Description

curl -X POST
'https://ag.us.clearapis.com/v1.0/zone/map/create?app_id={string}&app_key={string}' \
-H 'content-type: multipart/form-data;' \
-F account_id={string} \
-F user_id={string}\
-F field_id={string} \
-F file=@{string}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	Your Accounts API account ID. Can be provided in query string or form data.
user_id	string	yes	User ID provided by and used with the Accounts API. Can be provided in query string or form data.
field_id	string	yes	Specifies ID of given field to be used in mapping. User must have write privileges on field. Can be provided in query string or form data.
name_property	string	no	Name of feature attribute/property that exists in uploaded file. For each feature, the value will be retrieved and will be stored in the zone map feature properties under the key "name." This feature property can be modified after creation. Defaults to "null" if the property/attribute does not exist for a given feature or name_property was not provided.
id_property	string	no	Name of feature attribute/property that exists in uploaded file. For each feature, the value will be retrieved and will be stored in the zone map feature properties under the key "identifier." This feature property can not be modified after creation. Defaults to "null" if the property/attribute does not exist for a given feature or id_property was not provided. ** Currently id, Id, iD, & ID are not valid values and will cause an error when uploading a zone map.
file	file	yes	Accepted file types are shapefile or GeoJSON/JSON. Accepted file extensions are .json, .geojson, .tgz, tar.gz, and .zip. For this parameter HTTP POST method must be used and the file is expected to be provided in the form-data section of the request. There is currently a maximum limit of 20 management zones per zone map.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

Your Accounts API account ID. Can be provided in query string or form data.

user_id

string

yes

User ID provided by and used with the Accounts API. Can be provided in query string or form data.

field_id

string

yes

Specifies ID of given field to be used in mapping. User must have write privileges on field. Can be provided in query string or form data.

name_property

string

Name of feature attribute/property that exists in uploaded file. For each feature, the value will be retrieved and will be stored in the zone map feature properties under the key "name." This feature property can be modified after creation. Defaults to "null" if the property/attribute does not exist for a given feature or name_property was not provided.

id_property

string

Name of feature attribute/property that exists in uploaded file. For each feature, the value will be retrieved and will be stored in the zone map feature properties under the key "identifier." This feature property can not be modified after creation. Defaults to "null" if the property/attribute does not exist for a given feature or id_property was not provided. ** Currently id, Id, iD, & ID are not valid values and will cause an error when uploading a zone map.

file

yes

Accepted file types are shapefile or GeoJSON/JSON. Accepted file extensions are .json, .geojson, .tgz, tar.gz, and .zip. For this parameter HTTP POST method must be used and the file is expected to be provided in the form-data section of the request. There is currently a maximum limit of 20 management zones per zone map.

Response Object (JSON)

Field	Description
zone_map_id	Unique ID for the zone map.

Field

Description

zone_map_id

Unique ID for the zone map.

File Types

For all file types:

Files containing more than 20 features / management zones are not supported.
Files with size greater than 5mb are not supported.
Filenames with spaces are not supported, this includes the filenames in an archived file.
Compression formats other than zip and tgz/tar.gz are not supported.
File name must have one of the following extensions: .json, .geojson, .tgz, tar.gz or .zip.
Only feature types of polygon and multipolygon is currently supported.
When creating a zip or tgz archive, the shapefile or GeoJSON/JSON file[s] must be in root directory for the archive.

For Shapefile:

The shapefile must be archived with one of the following file types: zip or tgz/tar.gz.
The archive file must contain one shapefile.
The archive file must contain one each of: .shp, .shx, .dbf, and .prj files that comprise the shapefile. Please note that the presence of nested directories in the zip file will cause a validation error, and extra files present in archive will be ignored.
The archive file must be created by selecting the required files and archiving them directly. If the files are moved to a folder, and then the folder is archived, it will cause an error upon uploading.

For JSON/GeoJSON:

The file must be one of the following file types: zip, tgz, tar.gz, JSON or GeoJSON.
Only a single JSON/GeoJson is supported.
The JSON/GeoJSON file must only contain polygon and multipolygon geometry types. The JSON/GeoJSON file must be valid with respect to GeoJSON specification RFC 7946 (http://geojson.org/).
When using zip or tgz, the archive file must be created by selecting a single JSON/GeoJSON file and archiving it directly.

Example Request

curl -X POST 'https://ag.us.clearapis.com/v1.0/zone/map/create?app_id=123456&app_key=jkl101' \
-H 'content-type: multipart/form-data;' \
-F account_id=abc-123 \
-F user_id=def-456 \
-F field_id=ghi-789 \
-F file=@/my_fields/field1/zone_maps/zone_map_shapefile.zip

Example Response

421-123

Modify Field Zone Map - v1.0

This endpoint allows users to modify specific properties for the target zone map. Currently, only "name" is modifiable.

URL Description

https://ag.us.clearapis.com/v1.0/zone/map/modify?app_id={string}&app_key={string}&account_id={string}&user_id={string}&zone_map_id={string}&name={string}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	Your Accounts API account ID. Can be provided in query string or form data.
user_id	string	yes	User must have write privileges for field that target zone map is on.
zone_map_id	string	yes	Unique ID for the zone map.
name	string	yes	Modifications for name property. Expected format is [ [<zone_id>, <value>], … ]

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

Your Accounts API account ID. Can be provided in query string or form data.

user_id

string

yes

User must have write privileges for field that target zone map is on.

zone_map_id

string

yes

Unique ID for the zone map.

name

string

yes

Modifications for name property. Expected format is [ [<zone_id>, <value>], … ]

Response Object

Returns "true" on success.

Example Request

https://ag.us.clearapis.com/v1.0/zone/map/modify?app_id=123&app_key=321&account_id=321&user_id=456&zone_map_id=31c&name=[[bbb,new_name],[ccc,new_name2],[ddd,null]]

Example Response

true

Get Field Zone Map - 1.0

This endpoint allows a user to retrieve a field zone map formatted as GeoJSON.

URL Description

https://ag.us.clearapis.com/v1.0/zone/map/get?app_id={string}&app_key={string}&account_id={string}&user_id={string}&zone_map_id={string}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	Your Accounts API account ID. Can be provided in query string or form data.
user_id	string	yes	User ID provided by and used with the Accounts API. Can be provided in query string or form data.
zone_map_id	string	yes	Unique ID for the zone map.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

Your Accounts API account ID. Can be provided in query string or form data.

user_id

string

yes

User ID provided by and used with the Accounts API. Can be provided in query string or form data.

zone_map_id

string

yes

Unique ID for the zone map.

Response Object (JSON)

GeoJSON FeatureCollection. Please refer to RFC 7946 (http://geojson.org/) for further description.

Field	Description
zone_map_id	ID generated when creating the zone_map. This is added for convenience and not part of the GeoJSON specification.
name	User defined value. This corresponds to what was provided at zone creation through the id_property and name_property fields.
identifer	User defined value.

Field

Description

zone_map_id

ID generated when creating the zone_map. This is added for convenience and not part of the GeoJSON specification.

name

User defined value. This corresponds to what was provided at zone creation through the id_property and name_property fields.

identifer

User defined value.

Example Request

https://ag.us.clearapis.com/v1.0/zone/map/get?app_id=123&app_key=321&account_id=def&user_id=cba&zone_map_id=abc

Example Response

{
	"features":[{
			"geometry":{
				"coordinates":[
					[
						[
							-99.6204224,
							48.194588
						],
						[
							-99.6204125,
							48.194694
						],...
					]
				],
				"type":"Polygon"
			},
			"id":"abc",
			"properties":{
				"identifier":null,
				"name":null,
				"organic_matter":[
					[
						0,
						2.830984454116745
					],
					[
						2,
						2.830984454116745
					],...
				],
				"surface_area":70678.101016,
				"texture_classes":[
					[
						0,
						8
					],
					[
						2,
						8
					],...
				]
			},
			"type":"Feature"
		},
		{
			"geometry":{
				"coordinates":[
					[
						[
							-99.6201228,
							48.190272
						],
						[
							-99.6201059,
							48.190341
						],...
					]
				],
				"type":"Polygon"
			},
			"id":"bcd",
			"properties":{
				"identifier":null,
				"name":null,
				"organic_matter":[
					[
						0,
						3.173506909608841
					],
					[
						5,
						3.173506909608841
					], ...
				],
				"surface_area":23653.447038,
				"texture_classes":[
					[
						0,
						8
					],
					[
						5,
						8
					],...
				]
			},
			"type":"Feature"
		},
		{
			"geometry":{
				"coordinates":[
					[
						[
							-99.6204332,
							48.187186
						],
						[
							-99.6204165,
							48.187165
						],
						[
							-99.6204121,
							48.187038
						],...
					]
				],
				"type":"Polygon"
			},
			"id":"cde",
			"properties":{
				"identifier":null,
				"name":null,
				"organic_matter":[
					[
						0,
						3.2326898303213
					],
					[
						5,
						3.2326898303213
					],...
				],
				"surface_area":10721.575965,
				"texture_classes":[
					[
						0,
						8
					],
					[
						5,
						8
					],...
				]
			},
			"type":"Feature"
		},
		{
			"geometry":{
				"coordinates":[
					[
						[
							-99.6204366,
							48.196355
						],
						[
							-99.6200222,
							48.196327
						],...
					]
				],
				"type":"Polygon"
			},
			"id":"def",
			"properties":{
				"identifier":null,
				"name":null,
				"organic_matter":[
					[
						0,
						1.775980384521235
					],
					[
						5,
						1.775980384521235
					],...
				],
				"surface_area":135256.942854,
				"texture_classes":[
					[
						0,
						3
					],
					[
						2,
						3
					],...
				]
			},
			"type":"Feature"
		},
		{
			"geometry":{
				"coordinates":[
					[
						[
							-99.620423,
							48.195236
						],
						[
							-99.6204135,
							48.195181
						]
					],
					[
						[
							-99.6201209,
							48.190109
						],
						[
							-99.620078,
							48.189148
						],...
					],...
				],
				"type":"Polygon"
			},
			"id":"fed",
			"properties":{
				"identifier":null,
				"name":null,
				"organic_matter":[
					[
						0,
						2.5195164080146406
					],
					[
						2,
						2.5195164080146406
					], ...
				],
				"surface_area":544202.56221,
				"texture_classes":[
					[
						0,
						8
					],
					[
						2,
						8
					],...
				]
			},
			"type":"Feature"
		},
		{
			"geometry":{
				"coordinates":[
					[
						[
							-97.198935,
							48.187443999999996
						],
						[
							-97.198694,
							48.187494
						],...
					]
				],
				"type":"Polygon"
			},
			"id":"edc",
			"properties":{
				"identifier":null,
				"name":null,
				"organic_matter":[
					[
						2,
						2.8952366962139284
					],
					[
						5,
						2.8952366962139284
					],...
				],
				"surface_area":153728.072856,
				"texture_classes":[
					[
						70,
						8
					],
					[
						100,
						4
					],...
				]
			},
			"type":"Feature"
		}
	],
	"type":"FeatureCollection",
	"zone_map_id":"123"
}

Get Zone Map Properties - 1.0

This endpoint allows for the retrieval of zone map properties.

URL Description

https://ag.clearapis.com/v1.0/zone/map/get/properties?app_id={string}&app_key={string}&account_id={string}&zone_map_id={string}&user_id={string}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
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.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

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.

Response Object (JSON)

Field	Description
identifier	Contains a unique value representing the resource as it is known in your system, which correspond to what was provided at zone creation through the id_property and name_property fields.
name	A name can be provided, e.g. "zone A." This corresponds to what was provided at zone creation through the id_property and name_property fields.
organic_matter	Organic matter of the zone (percentage).
surface_area	Surface area of the zone (square meters).
texture_classes	Soil textures of the zone (enumerable value based on texture class - see Appendix for USDA Texture Class information).

Field

Description

identifier

Contains a unique value representing the resource as it is known in your system, which correspond to what was provided at zone creation through the id_property and name_property fields.

name

A name can be provided, e.g. "zone A." This corresponds to what was provided at zone creation through the id_property and name_property fields.

organic_matter

Organic matter of the zone (percentage).

surface_area

Surface area of the zone (square meters).

texture_classes

Soil textures of the zone (enumerable value based on texture class - see Appendix for USDA Texture Class information).

Example Request

https://ag.clearapis.com/v1.0/zone/map/get/properties?app_id=123&app_key=321&account_id=abc-123&user_id=aaa-123

Example Response

{
  "abc-bbb":{
    "identifier":null,
    "name":null,
    "organic_matter":[
      [
        [
          0.0,
          5.0
        ],
        [
          1.0,
          7.0
        ]
      ]
    ],
    "surface_area":4600,
    "texture_classes":[]
  },
  "bbb-cde":{
    "identifier":null,
    "name":null,
    "organic_matter":[],
    "surface_area":5000,
    "texture_classes":[
      [
        [
          0.0,
          7
        ],
        [
          8.0,
          12
        ],...
      ]
    ]
  },
}

Get Field Zone Map Source File - 1.0

This endpoint allows a user to retrieve the file uploaded to create the field zone map.

URL Description

https://ag.us.clearapis.com/v1.0/zone/map/get/source_file?app_id={string}&app_key={string}&account_id={string}&user_id={string}&zone_map_id={string}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	Your Accounts API account ID. Can be provided in query string or form data.
user_id	string	yes	User ID provided by and used with the Accounts API. Can be provided in query string or form data.
zone_map_id	string	yes	Unique ID for the zone map.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

Your Accounts API account ID. Can be provided in query string or form data.

user_id

string

yes

User ID provided by and used with the Accounts API. Can be provided in query string or form data.

zone_map_id

string

yes

Unique ID for the zone map.

Response Object

Response contains the original source file used to create the zone map. The file in the response will have the same name and format as the source_file uploaded when creating the zone map.

Example Request

https://ag.us.clearapis.com/v1.0/zone/map/get/source_file?app_id=123&app_key=321&account_id=abc&user_id=def&zone_map_id=123

Example Response

Response will be a file.

Get Zone Map ID by Field - 1.0

This endpoint allows for the retrieval of zone map IDs by field.

URL Description

https://ag.clearapis.com/v1.0/zone/map/get/by_field?app_id={string}&app_key={string}&account_id={string}&user_id={string}&field_id={string}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
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	Specifies ID of given field to be used in mapping. User must have write privileges on field. Can be provided in query string or form data.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

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

Specifies ID of given field to be used in mapping. User must have write privileges on field. Can be provided in query string or form data.

Response Object (JSON)

Field	Description
zone_map_id	Unique ID for the zone map.
created	Field creation time in the form of a Unix timestamp.

Field

Description

zone_map_id

Unique ID for the zone map.

created

Field creation time in the form of a Unix timestamp.

Example Request

https://ag.clearapis.com/v1.0/zone/map/get/by_field?app_id=123&app_key=321&account_id=abc-123&zone_map_id=bca-321&user_id=aaa-123

Example Response

[{
    "zone_map_id":"aaa-bbb",
    "created":1542396565
  },
  {
    "zone_map_id":"bbb-123",
    "created":1542396733
  },...
]

Create or Modify Soil Organic Matter - 1.0

This endpoint allows a user to create or modify zone aware organic matter levels.

URL Description

https://ag.clearapis.com/v1.0/zone/map/soil/organic_matter/modify?app_id={string}&app_key={string}&org_matter=[[{zone_id},({start_depth},{organic_matter_percentage}),...],...]&account_id={account_id}&user_id={user_id}&zone_map_id={zone_map_id}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
account_id	string	yes	A unique account ID provided by your account representative.
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.
zone_map_id	string	yes	Unique ID for the zone map.
org_matter	string	yes	Lists containing the zone_id, and all applicable start_depths and organic matter percentages. The format of this variable is: [[zone_id,(start_depth,organic_matter_percentage),…],…]. Acceptable values for start_depth are 0.0-200.0. Please note that a start_depth of 0 is required. Acceptable values for organic_matter_percentage are 0.0-100.0. If a sample is unknown or missing, the (start_depth, organic_matter_percentage) should be (null). Example: [{{zone_id}},(null)]. With the exception of the unknown or missing example above, both (depth & organic percentage) values are required.

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

account_id

string

yes

A unique account ID provided by your account representative.

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.

zone_map_id

string

yes

Unique ID for the zone map.

org_matter

string

yes

Lists containing the zone_id, and all applicable start_depths and organic matter percentages. The format of this variable is: [[zone_id,(start_depth,organic_matter_percentage),…],…].

Acceptable values for start_depth are 0.0-200.0. Please note that a start_depth of 0 is required.

Acceptable values for organic_matter_percentage are 0.0-100.0.

If a sample is unknown or missing, the (start_depth, organic_matter_percentage) should be (null). Example: [{{zone_id}},(null)].

With the exception of the unknown or missing example above, both (depth & organic percentage) values are required.

Response Object (JSON)

Field	Description
identifier	Contains a unique value representing the resource as it is known in your system. This can be used to correlate the unique ID’s generated by the ClearAg API with other systems.
name	A name can be provided, e.g. "zone A."
organic_matter	Percent of organic matter in sample.
surface_area	Surface area of the zone.
texture_classes	Soil textures of the zone.

Field

Description

identifier

Contains a unique value representing the resource as it is known in your system. This can be used to correlate the unique ID’s generated by the ClearAg API with other systems.

name

A name can be provided, e.g. "zone A."

organic_matter

Percent of organic matter in sample.

surface_area

Surface area of the zone.

texture_classes

Soil textures of the zone.

Example Request

https://ag.clearapis.com/v1.0/zone/map/soil/organic_matter/modify?app_id=123&app_key=321&org_matter=[[123-bcd,(0,35.78),(8,52)],[321-cba,(null)]]&account_id=abc-123&user_id=bcd-234&zone_map_id=cde-345

Example Response

{
  "123-bcd":{
    "identifier":null,
    "name":null,
    "organic_matter":[
      [
        [
          0.0,
          35.78
        ],
        [
          8.0,
          52.0
        ]
      ]
    ],
    "surface_area":544202.562212,
    "texture_classes":[]
  },
  "321-cba":{
    "identifier":null,
    "name":null,
    "organic_matter":[],
    "surface_area":70678.101017,
    "texture_classes":[]
  },...
}

Zone Map Soil Texture Modify - 1.0

This endpoint allows a user to modify an existing zone aware soil texture map.

URL Description

https://ag.clearapis.com/v1.0/zone/map/soil/texture/modify?app_id={string}&app_key={string}&account_id={string}&user_id={string}&zone_map_id={string}&texture_classes={string}&texture_depth_unit={string}

Request Parameters

Parameter	Type	Required	Description
app_id	string	yes	API ID provided by DTN.
app_key	string	yes	API key provided by DTN.
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.
zone_map_id	string	yes	Target zone map used to provide the initial soil samples.
texture_classes	string	yes	The depth of the layer is defined by the top of each user provided layer. If there is only one layer, set the top of the layer to zero and the API will count it for the whole depth. For multiple layers, only the top of the depth layer is needed. For example, if working in zone_id_1 with a multi-texture class of sand and clay, the top layer of sand input would be (0,1). The clay layer five cm down would have an input of (5,12). The resulting request would be: [[{{zone_id_1}},(0,1),(5,12)]]. Please see the Appendix for the USDA Texture Class section.
texture_depth_unit	string	yes	The unit used when taking the soil sample. Acceptable units are "in" or "cm."

Parameter

Type

Required

Description

app_id

string

yes

API ID provided by DTN.

app_key

string

yes

API key provided by DTN.

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.

zone_map_id

string

yes

Target zone map used to provide the initial soil samples.

texture_classes

string

yes

The depth of the layer is defined by the top of each user provided layer. If there is only one layer, set the top of the layer to zero and the API will count it for the whole depth. For multiple layers, only the top of the depth layer is needed. For example, if working in zone_id_1 with a multi-texture class of sand and clay, the top layer of sand input would be (0,1). The clay layer five cm down would have an input of (5,12). The resulting request would be: [[{{zone_id_1}},(0,1),(5,12)]]. Please see the Appendix for the USDA Texture Class section.

texture_depth_unit

string

yes

The unit used when taking the soil sample. Acceptable units are "in" or "cm."

Response Object

Returns "true" on success.

Example Request

https://ag.clearapis.com/v1.0/v1.0/zone/map/soil/texture/modify?app_id=123&app_key=321&account_id=abc-def&texture_classes=[[123-abc,(0,1),(3,2)],[456-cba,None]]&user_id=def-789&zone_map_id=def-123&texture_depth_unit=in

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.
429 Too Many Requests - You have either hit your contractual per-minute limit on query requests or you are using incorrect credentials. If you continue to receive this error after checking these possible causes, please contact DTN support.
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

DTN 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 the 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 DTN 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 DTN 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 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).

Activity and Plant Codes

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

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

Activity Type

Subtype Code

Meaning

Planting

Generic

Planting

Barley

Planting

Corn

Planting

Spring Wheat

Planting

Canola

Planting

Sugar Beets

Planting

Cotton

Spraying

Generic

Harvesting

Generic

Row Crop Cultivating

Generic

Post-harvest Tillage

Generic

Pre-planting Tillage

Generic

Cutting

Generic

Cutting

Alfalfa

Soil Test

Generic

Fertilizer Treatment

Generic

Grain Moisture Test

Generic

Scouting Report

Generic

Irrigation

Generic

USDA Texture Classes

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

Changelog

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

9/17/20

Added the response “429 Too Many Requests” to the Common HTTP response codes table.

3/24/20

A maximum of 100 field IDs allowed in the Delete Field endpoint.