Field Boundaries API

API change history

This 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 and lat 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 and distance 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 optional op parameters. The geometry parameter should be a WKT POLYGON geometry: POLYGON((lat lon,lat lon,...)). The spatial relation operator op parameter takes values of intersects or within. The default operator is intersects. 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 example 
     https://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 degrees
  • lon represents the longitude of point of interest, in decimal degrees
  • distance 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

Try it

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

  • (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 the cursor 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

  • 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 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