Maps

Your integration can add many types of maps to a user's farm. Technically speaking a "map" is a layer that can appear within the user's view of their farm. These could be from drone photography, a yield map, or a drawing - as long as they can be geographically located over the farm.

The following methods are available over the Web API:

Method	Description
maps.create	Creates a new map
maps.delete	Deletes a map
maps.edit	Updates an existing map
maps.info	Gets information about a map

TiledMap model

Example model:

{
    "url_templates": [
        "https://tiles1.example.com/the-farm/{z}/{x}/{y}.png?token=abc123",
        "https://tiles2.example.com/the-farm/{z}/{x}/{y}.png?token=abc123"
    ],
    "projection": "EPSG:3857",
    "extent": [87897.33, 6618233.42, 91585.74, 6623399.02],
    "min_zoom": 12,
    "max_zoom": 17
}

All maps must be provided in a tiled format like that used on Google Maps and other map services, where the origin of x 0 and y 0 are in the top-left and z is a zoom level. Tiles are defined with one or more url_templates which give the location of a tile based on these values. You may specify more than one template if you wish for requests to be spread across several locations.

The map should be provided with an extent and zoom levels where tiles are available. No tiles will be loaded outside of the defined extent. Map tiles will be stretched or squashed if required at other zoom levels.

Field	Required	Description
url_templates	Required	URL templates for locating tiles. Must contain {x}, {y} and {z} placeholders. You may use {-y} if the tile origin is in the bottom left, rather than top-left.
projection	Required	Must be "EPSG:3857" for Web Mercator.
extent	Required	Array of coordinates that specify the limits of the map tiles, in the following order: [min_x, min_y, max_x, max_y], specified in the correct projection.
min_zoom	Required	minimum zoom level that tiles are available
max_zoom	Required	maximum zoom level that tiles are available

Web API maps.create

Creates a map on the farm.

Method URI	https://api.fieldmargin.com/v1/maps.create
HTTP Method	POST
Required scopes	maps:write

Request

Example request

{
    "name": "Drone plan 17",
    "timestamp": "2017-06-30T13:34:33+02:00",
    "tiles": {
        "url_templates": ["https://dronemapper.example.com/tiles/123/{z}/{x}/{y}.png?token=abc123"],
        "projection": "EPSG:3857",
        "extent": [87897.33, 6618233.42, 91585.74, 6623399.02],
        "min_zoom": 12,
        "max_zoom": 17
    }
}

Field	Required	Description
name	Required	Human friendly name
timestamp	Required	ISO 8601 date and time the map refers to
tiles	Required	Source tiles for the map

Response

Example response

{
    "map": {
        "id": "1f7e89ac-0a83-404e-a742-32ca837dd7ca",
        "name": "Drone plan 17",
        "timestamp": "2017-06-30T11:34:33Z",
        "tiles": {
            "url_templates": [
                "https://dronemapper.example.com/tiles/123/{z}/{x}/{y}.png?token=abc123"
            ],
            "projection": "EPSG:3857",
            "extent": [87897.33, 6618233.42, 91585.74, 6623399.02],
            "min_zoom": 12,
            "max_zoom": 17
        }
    }
}

The response will contain the request with the addition of the ID we have generated for the map. The timestamp field accepts a time zone but will be converted to UTC in the response.

Web API maps.delete

Deletes a map that your integration created.

Method URI	https://api.fieldmargin.com/v1/maps.delete
HTTP Method	POST
Required scopes	maps:write

Request

Example request

{
    "id": "6d6797c3-47c5-40a8-83e2-338002b21a42"
}

Field	Required	Description
id	Required	ID of the map to delete

Response

Example response

{
    "deleted": true
}

Returns an error with code not_found if the map does not exist or the client does not have access to it.

Web API maps.edit

Updates a map that your integration created.

Method URI	https://api.fieldmargin.com/v1/maps.edit
HTTP Method	POST
Required scopes	maps:write

Request

Example request

{
    "id": "cadf4cab-0d78-4ca9-8979-b350d41077fd",
    "name": "Drone plan 17 revised",
    "timestamp": "2017-06-30T15:32:31+02:00"
}

The request is the same as for creating a map, with the additional id field. If fields are omitted then their values will not be updated.

Field	Required	Request
id	Required	ID of the map to update
name	Optional	Human friendly name
timestamp	Optional	ISO 8601 date and time the map refers to
tiles	Optional	Source tiles for the map

Returns an error with code not_found if the map does not exist or the client does not have access to it.

Web API maps.info

Gives information about a map that your integration created.

Method URI	https://api.fieldmargin.com/v1/maps.info
HTTP Method	GET
Required scopes	None

Request

Specify the map to return as a URL argument.

Argument	Required	Description
id	Required	ID of the map

Response

Returns an error with code not_found if the map does not exist or the client does not have access to it.