Field Boundaries API
API change historyThis API returns field boundaries for 2.7 million fields in the UK.
Get field boundaries
Find and return field boundaries
This endpoint supports four forms of query:
Find the field in which a specific point falls.
- Provide the
lon
andlat
parameters only. For example:http://api.agrimetrics.co.uk/field-boundaries?lat=53.71002&lon=-0.98569
Find all the fields within a given radius of a point, where the radius is specified in metres.
- Provide
lon
,lat
anddistance
parameters only. For example:https://api.agrimetrics.co.uk/field-boundaries?lat=53.71002&lon=-0.98569&distance=200
Find all the fields which lie partially or fully within a shape.
- Provide the
geometry
and the optionalop
parameters. Thegeometry
parameter should be a WKTPOLYGON
geometry:POLYGON((lat lon,lat lon,...))
. The spatial relation operatorop
parameter takes values ofintersects
orwithin
. The default operator isintersects
. For example:https://api.agrimetrics.co.uk/field-boundaries?geometry=POLYGON((-2.8125 51.81540,-0.703125 51.81540,-0.703125 52.91552,-2.8125 52.91552,-2.8125 51.81540))&op=within
Return all fields in the given list of field IDs
- Provide a list of field IDs using the
id
parameter. For examplehttps://api.agrimetrics.co.uk/field-boundaries?id=C6BgTxUxhMG_OCGrLGW8qw&id=FmFjEA3-rb-yhMh1Tf9Dng&id=H61CuJtOF06uCn6Lwuq5mw&id=xPhFAJePqJHcEjfozkjPSg
In the above queries,
lat
represents the latitude of point of interest, in decimal degreeslon
represents the longitude of point of interest, in decimal degreesdistance
represents the radius of search from point of interest, in metres
All four forms of query may also take the pageNum and pageSize parameters, which control paging of results. Note that large queries may take a long time to run, even with a small pageSize. We recommend using a pageSize of 500 for large queries. Alternatively, the query may take a useCursor=1 parameter, which indicates that a cursor should be used. This will return partial results, with a "cursor" field (for the JSON results), and an X-Agrimetrics-Cursor header field, containing a cursor string. This cursor string may be used in subsequent queries, with the "cursor" parameter, to retrieve the next results in the result set. Each query will return a different cursor value, which can be used to get the next set of results. Any given cursor will remain active for one minute after the results are returned, after which it will be invalid. The number of results returned by each call using a cursor can be set with the "pageSize" parameter in the initial call.
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 Accept
header in the request. A zipped ESRI shapefile can be requested by specifying application/zip
as the Accept
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
Request
Request URL
Request parameters
-
(optional)number
Longitude of field search, in decimal degrees.
-
(optional)number
Latitude of field search, in decimal degrees.
-
(optional)number
distance of field search, in metres.
-
(optional)string
A WKT polygon:
POLYGON((lon lat,lon lat,lon lat,...))
comma separated list of coordinates, defining the outline of the shape as a closed loop. The first and last points must be the same. -
(optional)string
Spatial relation operator. Currently supported operators are
intersects
andwithin
.The default operator isintersects
-
(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
andsquare-metres
. The default unit ishectares
. -
(optional)string
ID of the field.
-
(optional)string
Set to
1
to use a cursored query: a cursor value will be returned in the results, and can be passed as thecursor
parameter to a subsequent query to retrieve additional results. -
(optional)string
Pass the
cursor
value from a previous query to return the next set of results.
Request headers
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 GET "https://api.agrimetrics.co.uk/field-boundaries/v1/?lon={number}&lat={number}&distance={number}&geometry={string}&op={string}&pageNum={number}&pageSize={number}&areaUnit={number}&id={string}&useCursor={string}&cursor={string}"
-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["lon"] = "{number}";
queryString["lat"] = "{number}";
queryString["distance"] = "{number}";
queryString["geometry"] = "{string}";
queryString["op"] = "{string}";
queryString["pageNum"] = "{number}";
queryString["pageSize"] = "{number}";
queryString["areaUnit"] = "{number}";
queryString["id"] = "{string}";
queryString["useCursor"] = "{string}";
queryString["cursor"] = "{string}";
var uri = "https://api.agrimetrics.co.uk/field-boundaries/v1/?" + queryString;
var response = await client.GetAsync(uri);
}
}
}
// // 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("lon", "{number}");
builder.setParameter("lat", "{number}");
builder.setParameter("distance", "{number}");
builder.setParameter("geometry", "{string}");
builder.setParameter("op", "{string}");
builder.setParameter("pageNum", "{number}");
builder.setParameter("pageSize", "{number}");
builder.setParameter("areaUnit", "{number}");
builder.setParameter("id", "{string}");
builder.setParameter("useCursor", "{string}");
builder.setParameter("cursor", "{string}");
URI uri = builder.build();
HttpGet request = new HttpGet(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
"lon": "{number}",
"lat": "{number}",
"distance": "{number}",
"geometry": "{string}",
"op": "{string}",
"pageNum": "{number}",
"pageSize": "{number}",
"areaUnit": "{number}",
"id": "{string}",
"useCursor": "{string}",
"cursor": "{string}",
};
$.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: "GET",
// 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",
@"lon={number}",
@"lat={number}",
@"distance={number}",
@"geometry={string}",
@"op={string}",
@"pageNum={number}",
@"pageSize={number}",
@"areaUnit={number}",
@"id={string}",
@"useCursor={string}",
@"cursor={string}",
];
NSString* string = [array componentsJoinedByString:@"&"];
path = [path stringByAppendingFormat:@"?%@", string];
NSLog(@"%@", path);
NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
[_request setHTTPMethod:@"GET"];
// 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
'lon' => '{number}',
'lat' => '{number}',
'distance' => '{number}',
'geometry' => '{string}',
'op' => '{string}',
'pageNum' => '{number}',
'pageSize' => '{number}',
'areaUnit' => '{number}',
'id' => '{string}',
'useCursor' => '{string}',
'cursor' => '{string}',
);
$url->setQueryVariables($parameters);
$request->setMethod(HTTP_Request2::METHOD_GET);
// 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
'lon': '{number}',
'lat': '{number}',
'distance': '{number}',
'geometry': '{string}',
'op': '{string}',
'pageNum': '{number}',
'pageSize': '{number}',
'areaUnit': '{number}',
'id': '{string}',
'useCursor': '{string}',
'cursor': '{string}',
})
try:
conn = httplib.HTTPSConnection('api.agrimetrics.co.uk')
conn.request("GET", "/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
'lon': '{number}',
'lat': '{number}',
'distance': '{number}',
'geometry': '{string}',
'op': '{string}',
'pageNum': '{number}',
'pageSize': '{number}',
'areaUnit': '{number}',
'id': '{string}',
'useCursor': '{string}',
'cursor': '{string}',
})
try:
conn = http.client.HTTPSConnection('api.agrimetrics.co.uk')
conn.request("GET", "/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
'lon' => '{number}',
'lat' => '{number}',
'distance' => '{number}',
'geometry' => '{string}',
'op' => '{string}',
'pageNum' => '{number}',
'pageSize' => '{number}',
'areaUnit' => '{number}',
'id' => '{string}',
'useCursor' => '{string}',
'cursor' => '{string}'
})
if query.length > 0
if uri.query && uri.query.length > 0
uri.query += '&' + query
else
uri.query = query
end
end
request = Net::HTTP::Get.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