Field Boundaries API

API change history

This API returns field boundaries for 2.7 million fields in the UK.

Post field boundaries

Find all the fields which lie partially or fully within a shape.

  • Provide the geometry as the request body and the optional op as query parameter. The geometry provided in the request body should be a GeoJSON feature collection or a GeoJSON geometry with type Polygon. The spatial relation operator op query parameter takes values of intersects or within. The default operator is intersects.

    An example curl request with the geometry provided as a GeoJSON geometry with type Polygon:

     curl -X POST \
      'https://api.agrimetrics.co.uk/field-boundaries?op=within' \
        -H 'Content-Type: application/json' \
        -H 'Accept: application/geo+json' \
        -H 'Ocp-Apim-Subscription-Key: < Your key goes here >' \
        -d ' {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      -1.43646240234375,
                      51.95865365978013
                    ],
                    [
                      -1.37054443359375,
                      51.95865365978013
                    ],
                    [
                      -1.37054443359375,
                      51.99333702056398
                    ],
                    [
                      -1.43646240234375,
                      51.99333702056398
                    ],
                    [
                      -1.43646240234375,
                      51.95865365978013
                    ]
                  ]
                ]
            }' 

The Content-Type of the default response produced by the API is application/json with embedded GeoJSON field shapes. However, a native GeoJSON feature collection can be requested by specifying application/geo+json as the Content-Type header in the request. A zipped ESRI shapefile can be requested by specifying application/zip as the Content-Type header.

Note: When a native GeoJSON feature collection is requested, the area is not provided as part of the response.

The id returned as part of the API response, can be used with other supporting Field Explorer products such as,

  • Field facts. Example:
     https://api.agrimetrics.co.uk/field-facts/UljfdxGNH8loV51UDtxlFA 
  • Field trends. Example:
     https://api.agrimetrics.co.uk/field-trends/UljfdxGNH8loV51UDtxlFA 
  • Field forecasts. Example:
     https://api.agrimetrics.co.uk/field-forecasts/UljfdxGNH8loV51UDtxlFA 

Try it

Request

Request URL

Request parameters

  • (optional)
    string

    Spatial relation operator. Currently supported operators are intersects and within.The default operator is intersects

  • (optional)
    number

    The page number of all the search results. Defaults to 1 (the first page).

  • (optional)
    number

    Limit the number of results per page of results. The maximum number of results returned per page is 500.

  • (optional)
    number

    The unit for the area returned. Supported units are hectares and square-metres. The default unit is hectares.

Request headers

  • string
    Subscription key which provides access to this API. Found in your Profile.

Request body

Responses

200 OK

Search results are returned.

Representations

{
  "totalResults": 0,
  "pageNum": 0,
  "pageSize": 0,
  "results": [
    {
      "shape": {},
      "id": "string",
      "area": {
        "value": 0.0,
        "unit": "string"
      },
      "type": "string"
    }
  ],
  "cursor": "string"
}
{
  "type": "object",
  "properties": {
    "totalResults": {
      "type": "integer",
      "description": "Total number of results found."
    },
    "pageNum": {
      "type": "integer",
      "description": "Page number returned (from 1)."
    },
    "pageSize": {
      "type": "integer",
      "description": "Size of pages in pagination."
    },
    "results": {
      "type": "array",
      "items": {
        "description": "The field boundary of a found field.",
        "format": "list of polygons",
        "type": "object",
        "properties": {
          "shape": {
            "type": "object",
            "description": "GeoJSON object representing the field outline."
          },
          "id": {
            "type": "string",
            "description": "Unique ID of this field outline."
          },
          "area": {
            "type": "object",
            "description": "Area of the field",
            "properties": {
              "value": {
                "type": "number",
                "description": "Value"
              },
              "unit": {
                "type": "string",
                "description": "Unit of area."
              }
            }
          },
          "type": {
            "type": "string",
            "description": "The type of shape, which for this API is always a `Field`."
          }
        }
      }
    },
    "cursor": {
      "type": "string",
      "description": "Cursor to use in subsequent queries if using cursor-style pagination."
    }
  }
}
{
  "totalResults": 0,
  "pageNum": 0,
  "pageSize": 0,
  "results": [
    {
      "shape": {},
      "id": "string",
      "area": {
        "value": 0.0,
        "unit": "string"
      },
      "type": "string"
    }
  ],
  "cursor": "string"
}
{
  "type": "object",
  "properties": {
    "totalResults": {
      "type": "integer",
      "description": "Total number of results found."
    },
    "pageNum": {
      "type": "integer",
      "description": "Page number returned (from 1)."
    },
    "pageSize": {
      "type": "integer",
      "description": "Size of pages in pagination."
    },
    "results": {
      "type": "array",
      "items": {
        "description": "The field boundary of a found field.",
        "format": "list of polygons",
        "type": "object",
        "properties": {
          "shape": {
            "type": "object",
            "description": "GeoJSON object representing the field outline."
          },
          "id": {
            "type": "string",
            "description": "Unique ID of this field outline."
          },
          "area": {
            "type": "object",
            "description": "Area of the field",
            "properties": {
              "value": {
                "type": "number",
                "description": "Value"
              },
              "unit": {
                "type": "string",
                "description": "Unit of area."
              }
            }
          },
          "type": {
            "type": "string",
            "description": "The type of shape, which for this API is always a `Field`."
          }
        }
      }
    },
    "cursor": {
      "type": "string",
      "description": "Cursor to use in subsequent queries if using cursor-style pagination."
    }
  }
}
{
  "type": "object",
  "properties": {
    "totalResults": {
      "type": "integer",
      "description": "Total number of results found."
    },
    "pageNum": {
      "type": "integer",
      "description": "Page number returned (from 1)."
    },
    "pageSize": {
      "type": "integer",
      "description": "Size of pages in pagination."
    },
    "results": {
      "type": "array",
      "items": {
        "description": "The field boundary of a found field.",
        "format": "list of polygons",
        "type": "object",
        "properties": {
          "shape": {
            "type": "object",
            "description": "GeoJSON object representing the field outline."
          },
          "id": {
            "type": "string",
            "description": "Unique ID of this field outline."
          },
          "area": {
            "type": "object",
            "description": "Area of the field",
            "properties": {
              "value": {
                "type": "number",
                "description": "Value"
              },
              "unit": {
                "type": "string",
                "description": "Unit of area."
              }
            }
          },
          "type": {
            "type": "string",
            "description": "The type of shape, which for this API is always a `Field`."
          }
        }
      }
    },
    "cursor": {
      "type": "string",
      "description": "Cursor to use in subsequent queries if using cursor-style pagination."
    }
  }
}

400 Bad Request

Invalid/missing parameters.

Representations

{
  "statusCode": 0.0,
  "message": "string"
}
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "HTTP error code."
    },
    "message": {
      "type": "string",
      "description": "Developer friendly error message."
    }
  }
}
{
  "statusCode": 0.0,
  "message": "string"
}
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "HTTP error code."
    },
    "message": {
      "type": "string",
      "description": "Developer friendly error message."
    }
  }
}
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "HTTP error code."
    },
    "message": {
      "type": "string",
      "description": "Developer friendly error message."
    }
  }
}

404 Not Found

Search location does not match a known field.

Representations

{
  "statusCode": 0.0,
  "message": "string"
}
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "HTTP error code."
    },
    "message": {
      "type": "string",
      "description": "Developer friendly error message."
    }
  }
}
{
  "statusCode": 0.0,
  "message": "string"
}
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "HTTP error code."
    },
    "message": {
      "type": "string",
      "description": "Developer friendly error message."
    }
  }
}
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "HTTP error code."
    },
    "message": {
      "type": "string",
      "description": "Developer friendly error message."
    }
  }
}

Code samples

@ECHO OFF

curl -v -X POST "https://api.agrimetrics.co.uk/field-boundaries/v1/?op={string}&pageNum={number}&pageSize={number}&areaUnit={number}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--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
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

            // Request parameters
            queryString["op"] = "{string}";
            queryString["pageNum"] = "{number}";
            queryString["pageSize"] = "{number}";
            queryString["areaUnit"] = "{number}";
            var uri = "https://api.agrimetrics.co.uk/field-boundaries/v1/?" + 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://api.agrimetrics.co.uk/field-boundaries/v1/");

            builder.setParameter("op", "{string}");
            builder.setParameter("pageNum", "{number}");
            builder.setParameter("pageSize", "{number}");
            builder.setParameter("areaUnit", "{number}");

            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);
            request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");


            // 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
            "op": "{string}",
            "pageNum": "{number}",
            "pageSize": "{number}",
            "areaUnit": "{number}",
        };
      
        $.ajax({
            url: "https://api.agrimetrics.co.uk/field-boundaries/v1/?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
            },
            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://api.agrimetrics.co.uk/field-boundaries/v1/";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"op={string}",
                         @"pageNum={number}",
                         @"pageSize={number}",
                         @"areaUnit={number}",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"POST"];
    // Request headers
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
    // 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://api.agrimetrics.co.uk/field-boundaries/v1/');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'op' => '{string}',
    'pageNum' => '{number}',
    'pageSize' => '{number}',
    'areaUnit' => '{number}',
);

$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
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.urlencode({
    # Request parameters
    'op': '{string}',
    'pageNum': '{number}',
    'pageSize': '{number}',
    'areaUnit': '{number}',
})

try:
    conn = httplib.HTTPSConnection('api.agrimetrics.co.uk')
    conn.request("POST", "/field-boundaries/v1/?%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
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
    # Request parameters
    'op': '{string}',
    'pageNum': '{number}',
    'pageSize': '{number}',
    'areaUnit': '{number}',
})

try:
    conn = http.client.HTTPSConnection('api.agrimetrics.co.uk')
    conn.request("POST", "/field-boundaries/v1/?%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://api.agrimetrics.co.uk/field-boundaries/v1/')

query = URI.encode_www_form({
    # Request parameters
    'op' => '{string}',
    'pageNum' => '{number}',
    'pageSize' => '{number}',
    'areaUnit' => '{number}'
})
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['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# 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