1. Iframe Services

Iteris ClearAg Components are widgets that pull an amalgamation of data from the ClearAg APIs and provide that data in a pre-formatted table, chart, graph, etc. This document provides an overview of each component offered by Iteris.

For additional information related to creating a user, generating an authorization token, and gathering needed field and growth IDs, please refer to the Appendix.

2. Creating an Account

Before users can access the ClearAg Components, an active account ID, application ID, and application key are required. To obtain these values, please contact your Iteris account representative.

3. Common HTTP Response Codes

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

  • 200 OK - The request was successful.

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

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

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

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

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

  • 502 Bad Gateway - The service is not reachable.

4. Users

A unique user ID is required to use the ClearAg Components. After first receiving an account ID from Iteris, a new user can be added to that account by employing the Create User endpoint. Note that several different users may belong to a single account ID.

The Modify User endpoint allows for changes to various properties of a specified user ID, and the Remove User endpoint allows for the deletion of a specified user ID from the information database. Currently, any user within an account can modify or delete other users belonging to the same account; user rights management is the responsibility of the consuming application. Lastly, the Get User Information endpoint functions as a medium to obtain information on a specified user.

Please refer to the “Users” section of the Accounts API guide for further information.

5. Authorization Token

All components require an authToken to authenticate their request. This token must be included in all iframe calls. This needs to be done by doing the following:

Method URL Params Description Required

POST

https://iteris.clearag.com/v1/encToken

app_id

Obtained from Iteris

yes

app_key

Obtained from Iteris

yes

account_id

Obtained from Iteris

yes

user_id

Obtained from the ClearAg Accounts API

yes

expire

Number of seconds that the token is valid. Default is 86400 seconds.

no

Returns: Encoded authentication token string

Sample URL:

curl \
-X POST \
-H "Content-Type: application/json" \
-d '{"account_id":"accountId","user_id":"userId","app_key":"app_key","app_id":"app_id","expire":"600"}' \
'https://iteris.clearag.com/v1/encToken'

6. Crop Health/Growth Advisor

6.1. Growth Model

Description: A graphic representation of the projected growth for a particular crop at a particular location as well as the percentage likelihood of a frost occurring.

Use Case: By helping the grower to visualize the growth model output for a particular crop on this field, this tool can help growers both select the most appropriate crop for this field and to select the optimum plant date for that crop.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Please refer to the growth section in the Accounts API guide for additional information.

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

growth_id

UUID of the growth stage for this field/crop obtained from the ClearAg Accounts API. This is referred to as growth in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

< iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='https://iteris.clearag.com/component/standalone/chg-growthModel/1.0.0/index.html#
    {
        "growth_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name="growth"
    id="growth"
>
    <p>iframes are not supported by your browser.</p>
</iframe>
Growth model
Growth stages

7. Pest/Disease Advisor

7.1. Leaf Canopy Wetness

Description: A graphic description of relative canopy wetness. Also contains detailed weather information as well as field accessibility status.

Use Case: Helps the grower visualize and anticipate when their crop’s leaf canopy is most likely to be more wet or dry to guide crop management decisions on what pests to look for, what fertilizer(s) to use, what pesticides to spray, etc.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Please refer to the Crop Health API guide for additional information.

Leaf canopy wetness

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

field_id

UUID of the field obtained from the ClearAg Accounts API. This is referred to as field_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/pests-leafCanopy/1.0.0/index.html#
    {
        "field_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name=""
    id=""
>
    <p>iframes are not supported by your browser.</p>
</iframe>

7.2. Upcoming Spray Windows

Description: A graphic representation of forecasted upcoming spray windows in red, yellow, and green colors denoting good / marginal / poor status. Allows for user-supplied wind threshold and rainfree threshold to suit a wide variety of spray window types.

Use Case: Helps the grower to visualize potential spray application opportunities based on user supplied thresholds, with an intuitive red/yellow/green color scheme.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Please refer to the Crop Health API guide for additional information.

Upcoming spray window

frame Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

field_id

UUID of the field obtained from the ClearAg Accounts API. This is referred to as field_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/pests-sprayWindow/1.0.0/index.html#
    {
        "field_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name=""
    id=""
>
    <p>iframes are not supported by your browser.</p>
</iframe>

8. Planting Advisor

8.1. Planting Growth Model

Description: A graphic representation of the projected growth for a particular crop at a particular location. Also shows frost risk information.

Use Case: By helping the grower to visualize the growth model output for a particular crop on this field, this tool can help growers both select the most appropriate crop for this field and to select the optimum plant date for that crop.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Planting growth model

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

growth_id

UUID obtained from the ClearAg Accounts API. This is referred to as growth_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/planting-growthModel/1.0.0/index.html#
    {
        "growth_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name=""
    id=""
>
    <p>iframes are not supported by your browser.</p>
</iframe>

8.2. Planting Conditions

Description: A graphic depiction of the weather, soil temperature, and field accessibility values which would influence a grower’s decision to plant a particular crop on a particular field at a particular date and time.

Use Case: This component displays information relevant to the grower when they are in the process of planting. With access to forecast precipitation probabilities and amounts, the grower can make an informed decision about when they should plant and where.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Please refer to the Soil Conditions API guide for additional information.

Planting conditions

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

field_id

UUID of the field obtained from the ClearAg Accounts API. This is referred to as field_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/planting-conditions/1.0.0/index.html#
    {
        "field_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name=""
    id=""
>
    <p>iframes are not supported by your browser.</p>
</iframe>

9. Soil/Weather/Water Advisor

9.1. Soil Moisture & Topsoil Temperature

Description: A graphic representation of past, current, and future soil moisture and temperature for a selectable layer, a 14-day window centered on the current day, or a 100 day window spanning 90 days in the past to 9 days in the future.

Use Case: Provides detailed soil moisture and temperature information to help the grower make their own decision on whether or not to irrigate this field at any given time.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Please refer to the Soil Conditions API guide for additional information.

Soil moisture topsoil temperature

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

field_id

UUID of the field obtained from the ClearAg Accounts API. This is referred to as field_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/sww-soilTempMoisture/1.0.0/index.html#
    {
        "field_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name=""
    id=""
>
        <p>iframes are not supported by your browser.</p>
</iframe>

9.2. Current Conditions

Description: A graphic depiction of the current weather conditions at this particular field, along with 24-hour, 90-day, and YTD accumulated precipitation.

Use Case: This component is useful to the user when they are interested in viewing accumulated precipitation values as well as at-a-glance soil and weather information.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Please refer to the Field Weather API guide for additional information.

Current conditions

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

field_id

UUID of the field obtained from the ClearAg Accounts API. This is referred to as field_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/sww-nowcast/1.0.0/index.html#
    {
        "field_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name=""
    id=""
>
    <p>iframes are not supported by your browser.</p>
</iframe>

9.3. Forecast

Description: A graphic depiction of the weather and field accessibility forecast, allowing the user to toggle between an hourly forecast to 72 hours in the future or daily values out to 9 days in the future.

Use Case: For a predefined field, this component gives the user general forecast weather information as well as the field accessibility information about the field soil condition.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Please refer to the Field Weather API guide for additional information.

Forecast

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

field_id

UUID of the field obtained from the ClearAg Accounts API. This is referred to as field_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/sww-forecast/1.0.0/index.html#
    {
        "field_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name=""
    id=""
>
    <p>iframes are not supported by your browser.</p>
</iframe>

10. Historical Advisor

10.1. Historical Weather

Description: A graphic depiction of the historic weather and field accessibility data, allowing the user to choose between hourly or daily values. Daily has a date range of up to 366 days and hourly up to 10 days. In addition to the graphic depiction, a table of the data can be downloaded as a CSV file.

Use Case: For a predefined field, this component gives the user general historic weather information as well as the field accessibility information about the field soil condition.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

Please refer to the Field Weather API guide and the Soil Conditions API guide for additional information.

Historical Advisor

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

field_id

UUID of the field obtained from the ClearAg Accounts API. This is referred to as field_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/historical/1.0.0/index.html#
    {
        "field_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c"
    }'
    name=""
    id=""
>
    <p>iframes are not supported by your browser.</p>
</iframe>

11. Nutrient Advisor

11.1. Throughput

Description: A graphical representation of the soil moisture and accumulated soil moisture fluxes (“throughput”) at different depths within the soil profile over time.

Use Case: Nitrates in the soil profile (which is the predominant form that nitrogen takes in the soil) move freely with water, such that they can be leached downward to ever-deeper levels within the soil profile, and possibly out of reach of the crop’s roots. The moisture throughput graphs depict the amount of water that has moved downward through different depths in the soil profile, relative to the range of conditions over the preceding 10 years. The closer the current year’s throughput for any particular depth is to the top of the historical range, the greater the relative risk that nitrogen has been lost to deeper levels.

Please note that this component is supported for all widths equal or greater than 768px (pixels) and undesirable results may occur for widths smaller than 768px.

iframe Parameters:

Parameter Description Required

authToken

Encoded token obtained from the encoding API (documented in section Authorization Token).

yes

dateformat

Date format requested. Format is as follows: ymd - 2017-03-15, dmy - 15/03/2017, and mdy - 03/15/2017. The default is set to “mdy.”

no

field_id

UUID of the field obtained from the ClearAg Accounts API. This is referred to as field_id in the ClearAg documentation.

yes

lang

Language requested. Language tag should conform to RFC 5646. If the language requested is not available, the system will return the default language English (en-us).

no

units

Unit format requested us-std (imperial) or si-std (metric). If no units are provided, the default will be us-std.

no

Sample HTML:

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/nutrients-throughput/1.0.0/index.html#
    {
        "field_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c",
    }'
    name=""
    id=""
>
    <p>iframes are not supported by your browser</p>
</iframe>
throughputComponent

12. Appendix

12.1. Components Overview

The ClearAg components provide an easy way to place information from the ClearAg APIs into a webpage or application as an iframe. Before these components can be used, some initial setup is required. The following appendix sections provide the basic steps to work within the ClearAg compoents using the current conditions and growth model components as examples.

Before a user can begin, an application ID, application key, and an account ID from an Iteris representative are required.

When reviewing example data sections, please replace everything between brackets “{}” and include the brackets with the stated string to render a usable string.

12.2. Creating a User

The ClearAg components use the ClearAg Accounts API to display information specific to a particular field or growth. Because of this, users must first create a ClearAg user ID. The Create User API call uses an account ID to generate a user ID. Please see example below.

http://ag.clearapis.com/v1.0/accounts/user/create?account_id={your_account_id}

This URL string will return a unique user ID. The parameters “name” and “email” are not used specifically by the components, but can be used within the Accounts API guide.

12.3. Generating an Authorization Token

Once a user ID is created, an authorization token can be generated. An authorization token is required to use all ClearAg components. A single authorization token can be used for multiple components. Making a POST request, like the example below, returns an authorization token.

curl \
-X POST \
-H "Content-Type: application/json" \
-d '{"account_id":"{your_account_ID}","user_id":"{your_user_ID}","app_key":"{your_app_key}","app_id":"{your_app_id}","expire":"600"}' \
'https://iteris.clearag.com/v1/encToken'

It is important to note that authorization tokens cannot be used indefinitely and will expire after 24 hours. The “expire” parameter is an optional argument that accepts integers and sets how long, in seconds, an authorization token will remain valid. If this parameter is omitted, the default is 86400 seconds.

12.4. Generating Field ID or Growth ID

Within the ClearAg Accounts API, a field is associated with a user and a user can have multiple fields. Likewise, growths are associated with a field and a field can have multiple growths. All components require either a field ID or a growth ID depending on whether the component needs to be associated with a particular field or growth.

As an example, the current conditions component requires a field ID, and the growth model component requires a growth ID. The Create Field call requires an account ID, user ID, a latitude/longitude pair, and the area of the field in acres.

http://ag.clearapis.com/v1.0/accounts/field/create?
account_id={your_account_id}&user_id={your_user_id}&latitude=45.9
&longitude=-90.45&acres=55.59

The Create Growth call requires an account ID, user ID, field ID, the plant date as a Unix timestamp, and a plant type. Plant type is an enumeration value representing the type of crop planted. The number “51” denotes corn. Additional plant types are listed within the Accounts API guide.

http://ag.clearapis.com/v1.0/accounts/growth/create/{your_field_id}/51?
account_id={your_account_id}&user_id={your_user_id}&plant_date=1464739200

Both fields and growths have additional arguments. Please refer to the Accounts API guide for additional information.

12.5. Generating a Component

Once a user has completed all above appendix section requirements, component information can be obtained.

Below is an example of a current conditions HTML iframe tag.

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/sww-nowcast/1.0.0/index.html#
    {
        "field_id":"{your_field_id}",
        "authToken":"{your_authorization_token}",
        "lang":"en-us",
        "units":"si-std"
    }'
>

Below is an example of a growth model HTML iframe tag.

<iframe
    frameborder="0"
    scrolling="yes"
    width="1000"
    height="2000"
    src='http://iteris.clearag.com/component/standalone/
planting-growthModel/1.0.0/index.html#
    {
        "growth_id":"{your_growth_id}",
        "authToken":"{your_authorization_token}",
        "lang":"en-us",
        "units":"si-std"
    }'
>

Please note that “lang” is an optional argument that accepts RFC 5646 conforming language tags. If the requested language is not available, the default language is English (en-us). The parameter “units” is another optional argument that accepts either “us-std” (imperial) or “si-std” (metric). If no units are provided, the default “us-std” will be used. As shown above, all components have a similar format, but use a different base URL in the “src” argument and use either a field ID or growth ID.