Field#

The API endpoints that operate over Field entities are described below.

GET `/v1/fields`#

Retrieve a list of the Fields registered by the client. The response is paginated. The GET parameter offset can be used to move between pages and the parameter limit can be used to set the maximum results per page (it is advised to leave it on 10 by default).

URL parameters#

client_field_id: Optional filter that will return only the field(s) where the custom client-provided ID is the one specified in the parameter.
offset: the number of the first result of the current page, as counted from the API response.
limit: maximum number of items to be shown in this list.

Response#

{
    "limit": 10,
    "offset": 0,
    "items": [
        {
            "id": "2f4f741a-c603-4467-a16e-04643e29e67d",
            "client_field_id": "<customer's own field id/name>",
            "client_id": "7ce37b37-5811-4c7b-9cd8-08d4a641b7e2",
            "boundary": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [-1.200301, 51.631711],
                        [-1.199344, 51.630631],
                        [-1.197821, 51.630611],
                        [-1.195106, 51.631424],
                        [-1.194516, 51.631996],
                        [-1.195578, 51.633029],
                        [-1.200309, 51.631711]
                    ]
                ]
            },
            "point": null,
            "area": 4.5478689,
            "land_use": "Crops",
            "country_code": "GBR",
            "climate_zone": "cool_temperate_moist",
            "created_at": "2023-09-01T11:32:06.942116+00:00",
            "updated_at": null
        }
    ]
}

id: The UUID of the Field.
client_field_id: custom ID given by the client to identify the Field in its own end. Can be anything the client wants, but it will always be shown as a string in the JSON response.
client_id: ID of the API client, this is your ID.
boundary: geographical field boundary, in GeoJSON representation. Otherwise is null.
point: geographical point, in GeoJSON representation, in case the Field boundary was calculated via the “fields detection” endpoints.
area: area of the field, in hectares.
land_use: the type of land where the field polygon has been located. Check the Field entity definition for further details.
country_code: country code, in ISO Alpha-3.
climate_zone: the world climate zone where the field has been located. Check the Field entity definition for further details.
created_at: timestamp of the creation of the Field object.
updated_at: timestamp of the update time of the Field object, if it was ever updated.

GET `/v1/fields/<field_id>`#

Show individual Field details.

URL parameters#

field_id: The UUID of the Field.

Response#

{
    "id": "1e3721ac-7c7e-4c98-99c6-51bb9f7cdaa9",
    "client_field_id": "<customer's own field id/name>",
    "client_id": "7ce37b37-5811-4c7b-9cd8-08d4a641b7e2",
    "boundary": {
        "type": "Polygon",
        "coordinates": [
            [
                [-335.9545969963074, 49.7019742234742],
                [-335.952730178833, 49.7019742234742],
                [-335.952730178833, 49.70304282073538],
                [-335.9545969963074, 49.70304282073538],
                [-335.9545969963074, 49.7019742234742]
            ]
        ]
    },
    "point": null,
    "area": 1.6005564100335083,
    "land_use": "Trees",
    "country_code": "UKR",
    "climate_zone": "cool_temperate_dry",
    "created_at": "2022-04-01T12:15:46.734228",
    "updated_at": "2022-04-18T09:36:01.398441"
}

id: UUID of the Field.
client_field_id: custom ID given by the client to identify the Field in its own end. Can be anything the client wants, but because of this it will always be shown as a string in the JSON response.
client_id: ID of the API client, this is your ID.
boundary: geographical field boundary, in GeoJSON representation.
point: geographical point, in GeoJSON representation, in case the Field boundary was calculated via the “fields detection” endpoints.
area: area of the field, in hectares.
land_use: the type of land where the field polygon has been located. Check the Field entity definition for further details.
country_code: country code, in ISO Alpha-3.
climate_zone: the world climate zone where the field has been located. Check the Field entity definition for further details.
created_at: timestamp of the creation of the Field object.
updated_at: timestamp of the update time of the Field object, if it was ever updated.

POST `/v1/fields`#

Create new Fields in MRV database.

New fields are submitted to MRV by the client just specifying their client_field_id and their boundaries in GeoJSON.

Warning

The maximum allowed number of fields to be created in a single HTTP request is 100.

Warning

The boundary must always be a GeoJSON representation of the field geometry in EPSG:4326 coordinates system.

Payload#

[
    {
        "client_field_id": "<customer's own field id/name>",
        "boundary": {
          "coordinates": [
            [
              [-0.34352940888157946, 39.366600293323444],
              [-0.34292715402179397, 39.36527838987834],
              [-0.3416188072579871, 39.365727946893855],
              [-0.34240104632840485, 39.36699632430228],
              [-0.34352940888157946, 39.366600293323444]
            ]
          ],
          "type": "Polygon"
        }
    }
]

An array of one or more new Fields data, each item being:

client_field_id: custom ID given by the client to identify the Field in its own end. Can be anything the client wants, but because of this it will always be shown as a string in the JSON response.
boundary: geographical field boundary, in GeoJSON representation.

The backend will automatically calculate the area of the field, so it will be shown next time the Field is accessed in the Field detail.

Response#

[
    {
        "id": "72baf839-5ad9-4847-afac-cdbf4987c335",
        "client_field_id": "<customer's own field id/name>",
        "client_id": "7ce37b37-5811-4c7b-9cd8-08d4a641b7e2",
        "boundary": {
          "type": "Polygon",
          "coordinates": [
            [
              [-0.34352940888157946, 39.366600293323444],
              [-0.34292715402179397, 39.36527838987834],
              [-0.3416188072579871, 39.365727946893855],
              [-0.34240104632840485, 39.36699632430228],
              [-0.34352940888157946, 39.366600293323444]
            ]
          ]
        },
        "point": null,
        "area": 1.78975411203405,
        "land_use": null,
        "country_code": null,
        "climate_zone": null,
        "created_at": "2022-04-01T12:13:26.637793",
        "updated_at": null
    }
]

An array containing all the Field detail items of the created fields, similar to GET /v1/fields/<field_id> response.

POST `/v1/fields/detection`#

Create new field from a pair of coordinates (latitude, longitude), with Field Boundary Detection.

Warning

This endpoint will be deprecated in April 2024. See the Deprecation Schedule for more details.

Note

The client must have been assigned to the FBD product to perform this action.

Payload#

{
    "client_field_id": "<customer's own field id/name>",
    "aoi": {
        "type": "Point",
        "coordinates": [-1.2072909384613695, 51.63535887083356]
    }
}

client_field_id: custom ID given by the client to identify the Field in its own end. Can be anything the client wants, but because of this it will always be shown as a string in the JSON response.
aoi: “Area Of Interest”. A coordinates point, longitude and latitude, in GeoJSON format.

Response#

{
  "request_id": "9b5b032d-df40-4df6-9453-674710a7a2c7",
  "status": "Completed",
  "created_at": "2023-12-01T11:27:11.818771+00:00",
  "updated_at": "2023-12-01T11:27:11.991837+00:00",
  "start_date": "2022-12-01",
  "end_date": "2023-12-01",
  "field": {
    "id": "729a8800-fde4-47fb-920c-d45ce7fee07a",
    "client_field_id": "Testing FBD 02",
    "client_id": "7ce37b37-5811-4c7b-9cd8-08d4a641b7e2",
    "boundary": {
      "type": "Polygon",
      "coordinates": [
        [
          [-1.207011863, 51.636298128],
          [-1.206437704, 51.636199432],
          [-1.206448342, 51.635929818],
          [-1.206163038, 51.635835534],
          [-1.205483488, 51.634746044],
          [-1.205916752, 51.634752667],
          [-1.208111416, 51.634066785],
          [-1.208914196, 51.635697691],
          [-1.208480922, 51.635691079],
          [-1.208033477, 51.636043951],
          [-1.207011863, 51.636298128]
        ]
      ]
    },
    "area": 3.495,
    "point": {
      "type": "Point",
      "coordinates": [-1.207290938, 51.635358871]
    },
    "land_use": null,
    "country_code": null,
    "climate_zone": null,
    "created_at": "2023-12-01T11:27:11.807651+00:00",
    "updated_at": "2023-12-01T11:27:11.837776+00:00"
  }
}

request_id: UUID of the Request object, as this Field creation is indeed a request for field boundary detection.
status: current status of the Request. One of Pending, Completed or Failed.
created_at: timestamp of the creation of the Field object.
updated_at: timestamp of the last update of the Field object, in case it has been updated. Otherwise is null.
start_date: starting date to be taken into account for the boundary detection analysis.
end_date: end date to be taken into account for the boundary detection analysis.
field: data of the Field object. Similar to GET /v1/fields/<field_id> response.

POST `/v1/fields/detection/_preview`#

Create new field from a pair of coordinates (latitude, longitude), with Field Boundary Detection. If area is provided then the boundary with closest matching area will be returned. If start_date and end_date are provided, then the field will be detected in the start_date / end_date date-range

Note

This endpoint will transition into the endpoint without _preview suffix. See the Deprecation Schedule for more details.

Note

The client must have been assigned to the FBD product to perform this action.

Payload#

{
    "client_field_id": "<customer's own field id/name>",
    "aoi": {
        "type": "Point",
        "coordinates": [-1.2072909384613695, 51.63535887083356]
    }
    "area": 0.0,
    "start_date": "YYYY-MM-DD",
    "end_date": "YYYY-MM-DD"
}

client_field_id: custom ID given by the client to identify the Field in its own end. Can be anything the client wants, but because of this it will always be shown as a string in the JSON response.
aoi: “Area Of Interest”. A coordinates point, longitude and latitude, in GeoJSON format.
area: an optional float value. If provided the boundary with closest matching area will be returned.
start_date: optional date in the YYYY-MM-DD format, can only be defined together with end_date. If provided the field will be detected in the start_date / end_date date-range.
end_date: optional date in the YYYY-MM-DD format, can only be defined together with start_date. If provided the field will be detected in the start_date / end_date date-range.

Response#

{
  "request_id": "9b5b032d-df40-4df6-9453-674710a7a2c7",
  "status": "Completed",
  "created_at": "2023-12-01T11:27:11.818771+00:00",
  "updated_at": "2023-12-01T11:27:11.991837+00:00",
  "start_date": "2022-12-01",
  "end_date": "2023-12-01",
  "field": {
    "id": "729a8800-fde4-47fb-920c-d45ce7fee07a",
    "client_field_id": "<customer's own field id/name>",
    "boundary": {
      "type": "Polygon",
      "coordinates": [
        [
          [-1.207011863, 51.636298128],
          [-1.206437704, 51.636199432],
          [-1.206448342, 51.635929818],
          [-1.206163038, 51.635835534],
          [-1.205483488, 51.634746044],
          [-1.205916752, 51.634752667],
          [-1.208111416, 51.634066785],
          [-1.208914196, 51.635697691],
          [-1.208480922, 51.635691079],
          [-1.208033477, 51.636043951],
          [-1.207011863, 51.636298128]
        ]
      ]
    },
    "area": 3.495,
  }
}

request_id: UUID of the Request object, as this Field creation is indeed a request for field boundary detection.
status: current status of the Request. One of Pending, Completed or Failed.
created_at: timestamp of the creation of the Field object.
updated_at: timestamp of the last update of the Field object, in case it has been updated. Otherwise is null.
start_date: starting date to be taken into account for the boundary detection analysis.
end_date: end date to be taken into account for the boundary detection analysis.
field: data of the Field object. Similar to GET /v1/fields/<field_id> response.

POST `/v1/fields/detection/bulk`#

Create new fields in bulk from an array of pairs of coordinates (latitude, longitude), with field boundary detection.

Warning

This endpoint will be deprecated in April 2024. See the Deprecation Schedule for more details.

Note

The client must have been assigned to the FBD product to perform this action.

Warning

The maximum allowed number of fields sent in a single bulk request is 100.

Payload#

[
    {
        "client_field_id": "Field 1",
        "aoi": {
            "type": "Point",
            "coordinates": [9.078826904296875, 55.06421406528486]
        }
    },
    {
        "client_field_id": "Field 2",
        "aoi": {
            "type": "Point",
            "coordinates": [9.210662841796875, 54.95238569063361]
        }
    }
]

An array of items similar to the one used in POST /v1/fields/detection payload.

Response#

{
    "request_id": "54ccfd97-ddc6-4206-b8e7-f5551bf2ccf4",
    "status": "Pending",
    "created_at": "2022-04-01 12:15:46.734228",
    "updated_at": "2022-04-01 12:15:46.734228",
    "start_date": "2022-01-01",
    "end_date": "2022-03-01",
    "fields": [
        {
            "id": "72baf839-5ad9-4847-afac-cdbf4987c335",
            "client_field_id": "Field 1",
            "client_id": "7ce37b37-5811-4c7b-9cd8-08d4a641b7e2",
            "boundary": null,
            "area": null,
            "point": {
                "type": "Point",
                "coordinates": [9.078826904, 55.064214065]
            },
            "created_at": "2022-04-01T12:13:26.637793",
            "updated_at": null
        },
        {
            "id": "1e3721ac-7c7e-4c98-99c6-51bb9f7cdaa9",
            "client_field_id": "Field 2",
            "client_id": "7ce37b37-5811-4c7b-9cd8-08d4a641b7e2",
            "boundary": null,
            "point": {
                "type": "Point",
                "coordinates": [9.210662842, 54.952385691]
            },
            "area": null,
            "created_at": "2022-04-01T12:15:46.734228",
            "updated_at": null
        }
    ]
}

Similar to the one in POST /v1/fields/detection response, but the fields field is an array with all the actual fields submitted.

Warning

Take into account that the boundary and the area fields will be set to null in the response of this API endpoint because, at the time the service is responding to the user request, they have not been calculated yet. The action of calculating the field boundaries and areas in bulk is a background process that might take some extra time, depending on the number of fields to be calculated. This is why that data is not immediately available for the user.

POST `/v1/fields/detection/bulk/_preview`#

Create new fields in bulk from an array of pairs of coordinates (latitude, longitude), with field boundary detection. If area is provided for one or more fields in the array then the boundary with closest matching area will be returned. If start_date and end_date are provided, then the field will be detected in the start_date / end_date date-range.

Note

This endpoint will transition into the endpoint without _preview suffix. See the Deprecation Schedule for more details.

Note

The client must have been assigned to the FBD product to perform this action.

Warning

The maximum allowed number of fields sent in a single bulk request is 100.

Payload#

{
  "start_date": "2024-02-08",
  "end_date": "2024-02-08",
  "fields": [
    {
        "client_field_id": "Field 1",
        "aoi": {
            "type": "Point",
            "coordinates": [9.078826904296875, 55.06421406528486]
        },
        "area": 0.0
    },
    {
        "client_field_id": "Field 2",
        "aoi": {
            "type": "Point",
            "coordinates": [9.210662841796875, 54.95238569063361]
        }
    }
  ]
}

An array of items similar to the one used in POST /v1/fields/detection/_preview payload.

Response#

{
    "request_id": "54ccfd97-ddc6-4206-b8e7-f5551bf2ccf4",
    "status": "Pending",
    "created_at": "2022-04-01 12:15:46.734228",
    "updated_at": "2022-04-01 12:15:46.734228",
    "start_date": "2022-01-01",
    "end_date": "2022-03-01",
    "fields": [
      {
        "id": "72baf839-5ad9-4847-afac-cdbf4987c335",
        "client_field_id": "Field 1"
      },
      {
        "id": "0e8d4330-dfbb-4eb4-ad5c-7c944f0f7af6",
        "client_field_id": "Field 2"
      }
    ]
}

Similar to the one in POST /v1/fields/detection response, but the fields field is an array with all the actual fields submitted.

Deprecation Schedule#

Ongoing changes on the MRV API will deprecate the existing Field Boundary Detection endpoints over the next months. The current endpoints will remain unchanged until they are finally deprecated, which is expected to be on 1st April 2024. The technical details of the changes are described below:

The payload structure of the FBD endpoints /v1/fields/detection and /v1/fields/detection/bulk is going to change.
This change will be implemented in the next two weeks, and all the changes will be available to clients through two new preview endpoints:
- /v1/fields/detection/_preview
- /v1/fields/detection/bulk/_preview
On 1st April 2024 the existing endpoints will be changed to work as the preview ones, and the preview ones will disappear.
This change will be a breaking change, meaning that if no migration steps are taken by the clients, the requests will fail following the switch in April.

Field

Contents

Field#

GET /v1/fields#

URL parameters#

Response#

GET /v1/fields/<field_id>#

URL parameters#

Response#

POST /v1/fields#

Payload#

Response#

POST /v1/fields/detection#

Payload#

Response#

POST /v1/fields/detection/_preview#

Payload#

Response#

POST /v1/fields/detection/bulk#

Payload#

Response#

POST /v1/fields/detection/bulk/_preview#

Payload#

Response#

Deprecation Schedule#

GET `/v1/fields`#

GET `/v1/fields/<field_id>`#

POST `/v1/fields`#

POST `/v1/fields/detection`#

POST `/v1/fields/detection/_preview`#

POST `/v1/fields/detection/bulk`#

POST `/v1/fields/detection/bulk/_preview`#