TillageAI - Beta

API change history

The Ag-Analytics® TillageAI tillage identification model exposed via API, uses mutlispectral harmonized Landsat/Sentinel data, as well as other data sources and artificial intelligence algorithms to determine whether a field has been tilled or not, and at what date of the year.

Tillage Identification

Service Overview

Similar to the crop identification models, there is also great value in being able to identify where tillage and no-till (a conservation practice) are being used, and to be able to construct histories.

The Ag-Analytics® TillageAI API provides the service in which a user may point to any field in any year, and be able to infer:

  1. Was the field tilled or not
  2. If tilled, what date it was tilled
  3. If tilled, depth and type of tillage

This API uses NDVI imagery, location, weather, and other available data to "predict", or determine, if a field has been tilled.

The Tillage Model is a “backfilling model”, meaning that it can determine whether a field was tilled in the past, rather than provide prediction as to whether a field will be tilled. The model uses a seven-week window of satellite imagery, so as long as the date requested is more than three weeks prior to the current date (i.e., if today is Monday of the 20th week of the year, the latest request that can be made is for the 16th week.).

 

Model Specifications

The Tillage Model predicts tillage using one of two models that have been trained on approximately 2,000 tillage records from real farming operations. The dataset of tillage operations is used for ground truthing to create a verification label. Without the ground-truth data, there would be no way to tell the model that it predicted tillage correctly, and no way to determine the accuracy of a trained model.

The models are trained on three categories of data. The first is the location of the field geospatially. Tillage practices may vary in different areas of the country, so the addition of geospatial coordinates can illuminate some of these relationships. The second is the week of the year. In combination with the location of the field, the week of the year can help determine whether a field is able to be tilled at a given time of year. For example, tilling in Florida happens at a different time than in Minnesota. Third, remote sensing satellite imagery is used to find patterns in the ground reflectance that happen before, during, and after tillage. The temporal reflectance patterns are the primary driver for the tillage model in determining whether the field has been tilled. Currently, the model uses a seven-week window of satellite imagery.

Request Parameters

Parameter Data Type Required? Default Options Description
SHAPE Geometry, file/text Yes - Geojson Desired area-of-interest, see Fig. 1 for example.
ModelType Text String No Neural Network "NN" (Neural Network)"TREE" (Decision Tree) Type of model to use for prediction. Default is "NN". Not necessary to specify for most cases.
TillageStartDate Text Yes - Date String"mm/dd/yyyy" The date that tillage began. Must be in years {2014, 2015, 2016, 2017, 2018}. For 2019, must be more than 3 weeks prior to the current date.Ex. "04/23/2017"
ScalarVariables Dictionary Yes - - Wrapper dictionary for any variables that need to be included along with ModelType and SHAPE. Does not have a value itself. Please see sample request for clarification.

Response Parameters
Parameter Data Type Description
feature_averages Dictionary Average value of each input used to predict tillage.
raster_filename String URL to use in GET request to retrieve predicted raster file.
rasterinfo List of Dictionaries Container for the features and metadata information for the raster.
attributes Dictionary Container for specific features regarding the tillage prediction raster.
CellSize List Size of a single cell in the raster in degrees. (0.0001, -0.0001) roughly corresponds to an 8 meter by 8 meter square on the Earth’s equator. (i.e., 0.0001 degrees ~= 8 meters)
CoordinateSystem String Information about the coordinate system being used for calculations.
Extent String Specifies the left bottom corner and right top corner in longitude and latitude respectively.
Legend List of Dictionaries List of the metadata features for the areas of the field that returned as till or no-till or both.
Area Float Specifies the number of acres that were till or no-till for a given field.
AreaPercent String Specifies a percentage of the field that returned either till or no-till. For example, if 50% of the field is “till”, then Area is 50%.
Count Integer Number of pixels that returned as till or no-till. Used to calculate area.
CountAllPixels Integer Total number of pixels that make up the field in the predicted tillage raster.
Till String Specifies whether the given section (or entire area) of the field has been tilled. Returns “Yes” for tillage and “No” for tillage not detected.
Value Integer Binary value for tillage detected or not. Tillage detected = 1, Tillage not detected = 0.
color String Color that can be used to display the feature when plotting in a GIS application. (Hexadecimal)
pngb64 String PNG image of the tillage raster encoded as base64. Actual raster file can be obtained with a GET request to the service.

Parameter Examples

ModelType

“NN”

SHAPE
JSON
"{\"type\":\"Feature\",\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[-89.199484,40.972729],[-89.199773,40.97258],[-89.200135,40.972415],[-89.20034,40.972318],[-89.200445,40.972177],[-89.200439,40.972001]]]},\"properties\":{\"OBJECTID\":5134895,\"CALCACRES\":122.651351,\"CALCACRES2\":null},\"id\":4861522}""

TillageStartDate

“04/23/2017”



Call API

Request

Request URL

Request parameters

  • (optional)
  • (optional)

Request headers

  • (optional)
    string

Request body

Request Parameters

Parameter Data Type Required? Default Options Description
SHAPE Geometry, file/text Yes - Geojson Desired area-of-interest, see Fig. 1 for example.
ModelType Text String No Neural Network "NN" (Neural Network)"TREE" (Decision Tree) Type of model to use for prediction. Default is "NN". Not necessary to specify for most cases.
TillageStartDate Text Yes - Date String"mm/dd/yyyy" The date that tillage began. Must be in years {2014, 2015, 2016, 2017, 2018}. For 2019, must be more than 3 weeks prior to the current date.Ex. "04/23/2017"
ScalarVariables Dictionary Yes - - Wrapper dictionary for any variables that need to be included along with ModelType and SHAPE. Does not have a value itself. Please see sample request for clarification.

Response Parameters
Parameter Data Type Description
feature_averages Dictionary Average value of each input used to predict tillage.
raster_filename String URL to use in GET request to retrieve predicted raster file.
rasterinfo List of Dictionaries Container for the features and metadata information for the raster.
attributes Dictionary Container for specific features regarding the tillage prediction raster.
CellSize List Size of a single cell in the raster in degrees. (0.0001, -0.0001) roughly corresponds to an 8 meter by 8 meter square on the Earth’s equator. (i.e., 0.0001 degrees ~= 8 meters)
CoordinateSystem String Information about the coordinate system being used for calculations.
Extent String Specifies the left bottom corner and right top corner in longitude and latitude respectively.
Legend List of Dictionaries List of the metadata features for the areas of the field that returned as till or no-till or both.
Area Float Specifies the number of acres that were till or no-till for a given field.
AreaPercent String Specifies a percentage of the field that returned either till or no-till. For example, if 50% of the field is “till”, then Area is 50%.
Count Integer Number of pixels that returned as till or no-till. Used to calculate area.
CountAllPixels Integer Total number of pixels that make up the field in the predicted tillage raster.
Till String Specifies whether the given section (or entire area) of the field has been tilled. Returns “Yes” for tillage and “No” for tillage not detected.
Value Integer Binary value for tillage detected or not. Tillage detected = 1, Tillage not detected = 0.
color String Color that can be used to display the feature when plotting in a GIS application. (Hexadecimal)
pngb64 String PNG image of the tillage raster encoded as base64. Actual raster file can be obtained with a GET request to the service.

Parameter Examples

ModelType

“NN”

SHAPE
JSON
"{\"type\":\"Feature\",\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[-89.199484,40.972729],[-89.199773,40.97258],[-89.200135,40.972415],[-89.20034,40.972318],[-89.200445,40.972177],[-89.200439,40.972001]]]},\"properties\":{\"OBJECTID\":5134895,\"CALCACRES\":122.651351,\"CALCACRES2\":null},\"id\":4861522}""

TillageStartDate

“04/23/2017”

{
"ModelType": "TREE",
"SHAPE": "{\"type\":\"Feature\",\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[-89.199484,40.972729],[-89.199773,40.97258],[-89.200135,40.972415],[-89.20034,40.972318],[-89.200445,40.972177],[-89.200439,40.972001],[-89.200404,40.971815],[-89.200245,40.971599],[-89.20004,40.971397],[-89.199869,40.971233],[-89.199865,40.971097],[-89.199952,40.970952],[-89.200264,40.97078],[-89.200517,40.970664],[-89.200903,40.970471],[-89.201168,40.970345],[-89.201324,40.970277],[-89.201407,40.970174],[-89.201428,40.970042],[-89.20271,40.970005],[-89.202738,40.970421],[-89.202844,40.970431],[-89.202851,40.970648],[-89.203123,40.970666],[-89.203216,40.973626],[-89.20332,40.973635],[-89.203281,40.972154],[-89.203277,40.972049],[-89.203227,40.970607],[-89.204645,40.97055],[-89.204639,40.970427],[-89.205456,40.970446],[-89.205638,40.970467],[-89.206002,40.970527],[-89.206306,40.97059],[-89.206516,40.970642],[-89.206711,40.97061],[-89.20688,40.970542],[-89.207086,40.970492],[-89.207267,40.970414],[-89.207449,40.970364],[-89.207667,40.970286],[-89.207849,40.970255],[-89.208057,40.970251],[-89.208287,40.970328],[-89.208494,40.970369],[-89.208672,40.970421],[-89.208866,40.970506],[-89.208972,40.970511],[-89.209009,40.970595],[-89.20893,40.970671],[-89.208736,40.970787],[-89.208535,40.970909],[-89.208325,40.971052],[-89.207907,40.971306],[-89.207633,40.971478],[-89.207313,40.971574],[-89.207065,40.971645],[-89.206566,40.971699],[-89.206246,40.971784],[-89.205998,40.971878],[-89.205548,40.972042],[-89.205013,40.97232],[-89.20468,40.972494],[-89.204246,40.972725],[-89.203988,40.972931],[-89.203819,40.973168],[-89.203666,40.973428],[-89.203616,40.973685],[-89.203552,40.973966],[-89.203548,40.9743],[-89.203411,40.974615],[-89.203284,40.974906],[-89.202723,40.975587],[-89.20283,40.975719],[-89.203383,40.975106],[-89.203522,40.974847],[-89.203658,40.974521],[-89.203723,40.974241],[-89.20381,40.97376],[-89.203891,40.973546],[-89.20407,40.973197],[-89.204197,40.973016],[-89.204369,40.972868],[-89.204686,40.972672],[-89.205018,40.972499],[-89.205351,40.972314],[-89.205742,40.972139],[-89.206047,40.971999],[-89.206367,40.971904],[-89.206907,40.971771],[-89.207303,40.971719],[-89.207551,40.971658],[-89.207846,40.971535],[-89.207938,40.971481],[-89.208059,40.971448],[-89.208267,40.971295],[-89.208534,40.971115],[-89.209089,40.970762],[-89.209108,40.971493],[-89.209143,40.972829],[-89.209176,40.974108],[-89.209236,40.977186],[-89.20442,40.977285],[-89.199613,40.977383],[-89.199533,40.974593],[-89.199484,40.972729]]]},\"properties\":{\"OBJECTID\":5102679,\"CALCACRES\":145.08999634,\"CALCACRES2\":null},\"id\":5102679}",
"ScalarVariables": {
"TillageStartDate": "04-23-2018"
}
}

Responses

200 OK

Representations

Code samples

@ECHO OFF

curl -v -X POST "https://ag-analytics.azure-api.net/tillage-model/?f={}&geometry={}"
-H "Content-Type: application/json"

--data-ascii "{body}" 
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers

            // Request parameters
            queryString["f"] = "{}";
            queryString["geometry"] = "{}";
            var uri = "https://ag-analytics.azure-api.net/tillage-model/?" + queryString;

            HttpResponseMessage response;

            // Request body
            byte[] byteData = Encoding.UTF8.GetBytes("{body}");

            using (var content = new ByteArrayContent(byteData))
            {
               content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
               response = await client.PostAsync(uri, content);
            }

        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://ag-analytics.azure-api.net/tillage-model/");

            builder.setParameter("f", "{}");
            builder.setParameter("geometry", "{}");

            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);
            request.setHeader("Content-Type", "application/json");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
            "f": "{}",
            "geometry": "{}",
        };
      
        $.ajax({
            url: "https://ag-analytics.azure-api.net/tillage-model/?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Content-Type","application/json");
            },
            type: "POST",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://ag-analytics.azure-api.net/tillage-model/";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"f={}",
                         @"geometry={}",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"POST"];
    // Request headers
    [_request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://ag-analytics.azure-api.net/tillage-model/');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Content-Type' => 'application/json',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'f' => '{}',
    'geometry' => '{}',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_POST);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
}

params = urllib.urlencode({
    # Request parameters
    'f': '{}',
    'geometry': '{}',
})

try:
    conn = httplib.HTTPSConnection('ag-analytics.azure-api.net')
    conn.request("POST", "/tillage-model/?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
}

params = urllib.parse.urlencode({
    # Request parameters
    'f': '{}',
    'geometry': '{}',
})

try:
    conn = http.client.HTTPSConnection('ag-analytics.azure-api.net')
    conn.request("POST", "/tillage-model/?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://ag-analytics.azure-api.net/tillage-model/')

query = URI.encode_www_form({
    # Request parameters
    'f' => '{}',
    'geometry' => '{}'
})
if query.length > 0
  if uri.query && uri.query.length > 0
    uri.query += '&' + query
  else
    uri.query = query
  end
end

request = Net::HTTP::Post.new(uri.request_uri)
# Request headers
request['Content-Type'] = 'application/json'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body