Fields

You can access information about all of the fields and boundaries on the farm.

A field may have many boundaries, one of which is marked as primary and can be used as a general purpose outline of the field. A field may also optionally have a field usage; this is a label defined by the user for the purpose of the field, which you could use to group fields together in your application.

Each field boundary is defined as a GeoJSON polygon; that is a single exterior ring plus optional interior rings (or holes) inside it. These polygons may have been drawn by humans or created by other integrations.

The following methods are available over the Web API:

Method	Description
fields.list	List all the fields on the farm
fields.primary-boundary	Gets the primary boundary of a field

Web API fields.list

Lists all of the fields on the farm and their current usages.

Method URI	https://api.fieldmargin.com/v1/fields.list
HTTP Method	GET
Required scopes	fields:read:all

Response

Example response

{
    "fields": [
        {
            "id": "e2b2b901-9e29-400a-9045-0ad81ec00188",
            "name": "Tall sheep",
            "usage_id": "d2bdcd21-e84f-4ea0-a2cb-d9b9e7731e1b"
        },
        {
            "id": "29187ee4-7792-4fcb-82e4-8b2f27d9477d",
            "name": "Top field",
            "usage_id": null
        },
        {
            "id": "5b65689a-4a44-4621-94c7-2f35ea23a302",
            "name": "Bottom field",
            "usage_id": null
        }
    ],
    "usages": [
        {
            "id": "d2bdcd21-e84f-4ea0-a2cb-d9b9e7731e1b",
            "name": "Sheep",
            "colour": "#90a519"
        }
    ]
}

The response gives a summary of each field:

Field	Description
id	Unique identifier for the field, useful for other API methods
name	Human readable name
usage_id	ID of the current usage of this field (optional)

And a summary of each field usage:

Field	Description
id	Unique identifier for the field usage, as found in the Field model
name	Human readable name
colour	Hex code for the colour chosen by the user

Web API fields.primary-boundary

Gives the primary boundary of a field. This is likely the most recent boundary and represents an outline of the field.

Method URI	https://api.fieldmargin.com/v1/fields.primary-boundary
HTTP Method	GET
Required scopes	fields:read:all

Request

Argument	Required	Description
field_id	Required	ID of the field

Response

Example response

{
    "boundary": {
        "id": "96b645e8-cf9e-4d17-9274-185125b9bc57",
        "name": "Outline",
        "polygon": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        0.8174624973715214,
                        51.063196063633995
                    ],
                    [
                        0.8174624973715214,
                        51.06329720364397
                    ],
                    ...
                    [
                        0.8174624973715214,
                        51.063196063633995
                    ]
                ]
            ]
        },
        "primary": true,
        "timestamp": "2018-01-18T11:35:25Z"
    }
}

The response contains the following information:

Field	Description
id	Unique identifier of this boundary
name	Human readable name
polygon	GeoJSON polygon for this boundary
primary	Whether this is the primary boundary for the field
timestamp	The date and time this boundary represents

Returns an error with code not_found if the field does not exist.