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, gathering needed field and growth IDs, and currently supported languages please refer to the Supplementary Information section of 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. 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.

4. 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'

5. Crop Health/Growth Advisor

5.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 Crop Health 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 Crop Health 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='http://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

6. Pest/Disease Advisor

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

6.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='https://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>

6.3. Spray Window Advisor

Description: A graphic representation of forecasted upcoming spray windows as indicated by favorable (green) or unfavorable (black & grey) windows. A five day spray window forecast is presented to the user based upon entered criteria.

Use Case: Helps the grower to visualize potential spray application opportunities based on user specified criteria, with an intuitive green (favorable) / grey & black (unfavorable) color scheme.

Please note that this component is supported for all widths equal or greater than 768px (pixels). However this component does support widths smaller than 768px with limited functionality.

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

Spray Window one
Spray Window two

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="768"
    height="1200"
    src='https://iteris.clearag.com/component/standalone/spray-advisor/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. Planting Advisor

7.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 of the growth stage for this field/crop obtained from the ClearAg Crop Health 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/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>

7.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='https://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>

8. Soil/Weather/Water Advisor

8.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='https://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>

8.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='https://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>

8.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='https://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>

9. Historical Advisor

9.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='https://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>

10. Nutrient Advisor

10.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='https://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

10.2. Nitrogen Optimizer

Description: This component is an advanced modeling tool to help determine when and how much fertilizer is required to obtain a desired yield.

Use Case: Given a crop type, maturity, yield target, plant date, and location, this tool provides the user with the ability to determine the stage-by-stage Nitrogen needs of a crop. This component allows users to model different fertilization strategies, and provides recommended fertilization rates given the fertilization type and application method.

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.

iframe Parameters:

Parameter Description Required

authToken

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

yes

growth_id

UUID of the growth stage for this field/crop obtained from the ClearAg Crop Health 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

dateformat

Preferred format for the display of dates. Valid options are mdy, ymd, or dmy. If no dateformat is specified, the default is mdy (i.e. May 10, 2017).

no

yield_goal

Target yield for current crop.

yes

yield_goal_unit

Target yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac.”

yes

previous_crop

Enumeration value of previous crop on field. Plant enumeration values can be found in the Crop Health API appendix.

no

previous_yield

Actual yield of the previous crop.

yes if previous crop is specified, no if previous crop is not specified

previous_yield_unit

Previous yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac.” Required if previous crop is specified. Note that “bu/ac” is not a valid yield unit for alfalfa, cotton, or vegetable.

yes if previous crop is specified, no if previous crop is not specified

previous_harvest_ date

Epoch timestamp valid near the time that the previous crop was harvested.2 Required if previous crop is specified. May not predate the planting or emergence date by more than 366 days.

yes if previous crop is specified, no if previous crop is not specified

output_unit

Specifies the unit of the area density data displayed. Accepted values are “lb/ac” or “kg/ha.”

yes

Sample HTML with previous yields:

< iframe
    frameborder="0"
    scrolling="yes"
    width="1024"
    height="900"
    src='https://iteris.clearag.com/component/standalone/ nutrients-nitrogen/1.0.0/index.html#
    {
        "growth_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c",
        "units":"us-std",
        "lang":"en-us",
        "dateformat":"mdy",
        "yield_goal":"140",
        "yield_goal_unit":"lb/ac",
        "output_unit":"lb/ac",
        "previous_harvest_date":"1464739200",
        "previous_yield":"105",
        "previous_yield_unit":"lb/ac"
    }'
>
    <p>iframes are not supported by your browser.</p>
</iframe>

Sample HTML without previous yields:

< iframe
    frameborder="0"
    scrolling="yes"
    width="1024"
    height="900" src='http://iteris.clearag.com/component/standalone/nutrients-nitrogen/1.0.0/index.html#
    {
        "growth_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c",
        "yield_goal":"140",
        "yield_goal_unit":"lb/ac",
        "output_unit":"lb/ac"
    }'
>
    <p>iframes are not supported by your browser.</p>
</iframe>
Nitrogen 1
Nitrogen 2
Nitrogen 4

10.2.1. Additional Information

The Nitrogen Optimizer works best when there are more inputs into the model. These inputs are not specified on the URL like other parameters, but are consumed directly by the model.

*The nitrogen advisor uses many sources for calculating your nitrogen profile and optional recommendation.

  • Weather – Forecast & Historical (ClearAg provided)

  • Soil Tests (optional - user provided)

  • Fertilizer Treatments (optional - user provided)

  • Previous Harvest Yields (optional - user provided)

Adding optional information will help train the model to a given location, which results in optimized recommendations created for the given field and crop.

*Collect the required information and any additional (but optional) activity information:

  • Previous crop (if any), previous crop yield, and previous harvest date

  • Current crop

  • Current crop desired yield

  • Any soil tests that have been performed recently

  • Any fertilizations that have been applied recently

  • Whether recommendations are wanted

    • For which data are recommendations wanted?

    • For which fertilizer type are recommendations wanted?

Activities should be entered first. Using the appropriate API call for the given activity, users will want to add the soil tests and fertilizations.

Both of these activities can be placed on the whitelist. This list controls what activities the nitrogen model consumes. The model will process activities on the whitelist while items not on the list will be ignored.

Using this whitelist will enable fine control over all the field activities the user wishes to consume.

Once the user has performed soil tests and fertilizer treatments and entered that information, the user needs to add a request for a recommendation.

The recommended process is as follows:
1. Create a fertilizer treatment recommendation for a particular date and type of fertilizer
2. Run the nitrogen model – view the recommendation
3. Delete the fertilizer treatment recommendation

It is suggested to delete the fertilizer treatment so recommendations do not get included in subsequent model runs (unless that is desired).

In order to make a fertilizer treatment recommendation, utilize the add fertilizer treatment endpoint with special parameters.

Users may only have one fertilizer treatment recommendation per day.

Recommendation are displayed and able to be printed showing the date to apply, the type of fertilizer and application rate needed to obtain the yield desired. Actual results may vary.

11. Harvest Advisor

11.1. In Field Dry Down

Description: This component helps users determine whether they are able to obtain a crop moisture percentage that is favorable to storing crops infield. This component’s accuracy is improved by consuming grain moisture tests.

Use Case: This model can assist a farmer or custom harvester in determining the best time to harvest a crop given a specific moisture percentage target. The harvest window can be used to schedule equipment across the fields and to find the time in which the crop would have the lowest moisture content, resulting in the lowest cost to dry down for long-term storage.

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.

iframe Parameters:

Parameter Description Required

authToken

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

yes

growth_id

UUID of the growth stage for this field/crop obtained from the ClearAg Crop Health 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

dateformat

Preferred format for the display of dates. Valid options are mdy, ymd, or dmy. If no dateformat is specified, the default is mdy (i.e. May 10, 2017).

no

Sample HTML:

< iframe
    frameborder="0"
    scrolling="yes"
    width="1024"
    height="900"
    src='https://iteris.clearag.com/component/standalone/infield-drydown/1.0.0/index.html#
    {
        "growth_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c",
        "units":"us-std",
        "lang":"en-us",
        "dateformat":"mdy"
    }'
>
    <p>iframes are not supported by your browser.</p>
</iframe>
Infield 1
Infield 2
Infield 3

11.2. Mechanical Dry Down

Description: This component assists users in determining cost and dry down using a variety of methods. These methods include infield, low temperature drying facilities, and high temperature drying facilities. Both low temperature and high temperature facilities can be created to accurately model a given user’s options. This component’s accuracy can be improved by consuming grain moisture tests.

Use Case: The mechanical dry down component allows a user to model given drying facilities in order to determine the cost of drying grain to a specific level at a specific time. This model also assists in determining the throughput capability of a drying facility, and the time required to meet the target moisture. In addition, this model will warn the user if target moisture level can not be met with a specific drying facility.

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.

The recommended process is as follows:
1. Create drying facility
2. Use mechanical dry down component

Please note that the the drying facility ID is required for the mechanical dry down component to work correctly.

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

iframe Parameters:

Parameter Description Required

authToken

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

yes

growth_id

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

yes

grain_unit

The unit of measure for the grain to be dried. Valid options are: “bu” (bushel) or “mt” (metric ton)

yes

target_moisture_ content_wb

The desired moisture content of the crop. A numerical float between 12 to 25 is required.

yes

drying_facility_ids

UUID(s) of the facility obtained from the ClearAg Crop Health API. This is referred to as the drying_facility_id in the ClearAg documentation. Users can provide up to four drying facilities by concatenating the facilities with a comma. Please note that the model is extremely sensitive to accurate facility configuration. If issues occur, please verify the drying facility configuration.

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

dateformat

Preferred format for the display of dates. Valid options are mdy, ymd, or dmy. If no dateformat is specified, the default is mdy (i.e. May 10, 2017).

no

Sample HTML:

< iframe
    frameborder="0"
    scrolling="yes"
    width="1024"
    height="900"
    src='http://iteris.clearag.com/component/standalone/ mechanical-drydown/1.0.0/index.html#
    {
        "growth_id":"XXXXX-XXXXXX-XXXXX-XXXXX",
        "grain_unit":"bu",
        "target_moisture_content_wb":28,
        "drying_facility_ids":"XXXXX-XXXXXX-XXXXX-XXXXX,XXXXX-XXXXXX-XXXXX-XXXXX",
        "authToken":"cfd1f9f7694162c427c5bbc48fedce9c",
        "units":"us-std",
        "lang":"en-us",
        "dateformat":"mdy"
     }'
>
    <p>iframes are not supported by your browser.</p>
</iframe>
Mechanical 3

Appendix

Appendix A: Supplementary Information

A.1. Common HTTP response codes

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

  • 200 OK - The request was successful.

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

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

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

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

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

  • 502 Bad Gateway - The service is not reachable.

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

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

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

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

A.6. 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='https://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='https://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.

A.7. Languages

All components currently support the following languages:

  • English

  • Spanish

  • Portuguese

  • German

  • French

  • Dutch

  • Italian

  • Ukrainian

  • Russian

  • Japanese

6.3 Spray Window Advisor currently only supports English

Appendix B: Changelog

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

v3.3.3

The link for 'growth_id' was changed to reference the Crop Health API guide, as opposed to the Accounts API guide.

v3.4.0

Language offering information has been added to the Appendix.