Overview

While our Swagger documentation is rather technical this page will provide a functional overview of each available interface method. Apart from that core concepts of 365 will be described.

Company

An external partner can retrieve information about the company and the account owner. The company is the tenant for all other company related data. Each dataset a user creates belongs to one company and is not shared among other companies. Within one company multiple users can exist. The one who registered the company is the account owner. A company contains at least one physical farm (see Farms) and one person (see Persons), and it can contain a list of machines (see Machines). A login can be created by the account owner for other persons to use 365FarmNet or the app.

At the moment only the account owner can use partner integrations.

Crop cultivation

by harvest year

An external partner can retrieve information about crop cultivation for a specific harvest year of the company. Given the harvest year it returns information about the fields, cultures (=crops), and seed varieties grown on them, as well as the amount of seeds used, and harvest yield obtained.

A harvest year covers the period starting just after the harvest of the previous crop on a field to the harvest of the dedicated main crop. It is therefore not identified by a dedicated date or period but by the calendar year in which the main crop is harvested.

A main crop normally is sown and harvested within one harvest year or vegetation period. An exception are permanent crops, as they can be harvested several times after been sown.

A catch crop normally is cultivated between two main crops for soil protection reasons and can either be harvested or left on the field. It is linked with the following main crop and therefore present in the same harvest year.

A permanent crop is present on the field even after harvesting and can only be terminated by a tilling documentation. It can be harvested more than once without being sown again.

Details of the transferred items:

  • The culture (=crop) for the harvest year includes the seed variety in booked or planned sowing documentations with their acreage.
  • If there is more than one variety within a culture on the same field, all varieties with their acreage are transferred.
  • If there is more than one culture on the same field in the harvest year, all cultures and seed varieties with their acreages are transferred.
  • If there is a sowing documentation but no harvesting on the field, the state for the culture is "sown" (note: planned and preliminary documentations are ignored!)
  • If the field is already harvested, the state for the culture is "harvested" (note: planned and preliminary documentations are ignored!)
  • If the field is not yet harvested, the amount of yield is taken from the crop rotation planning.
  • If the culture on the field is caused only by a crop rotation planning for the harvest year, the state for the culture is "planned".
  • If there is more than one documented harvest on the field, the yield amounts are added.
  • If there is more than one harvested product (corn/crop, straw/foliage, whole plant) on the field, the yield amounts are only added for products of the type corn/crop.
  • If there is no harvest of straw/foliage on a field, there is an attribute showing that crop residue is left on the field (for nutrition reasons).
  • If there is a sowing documentation but the culture is terminated via any tillage documentation afterwards, neither the sowing information is transferred, nor any planned nor harvested yield amount.
  • If different kinds of products are harvested on the field in a harvest year, only the harvest figures of the most valuable product is provided by the API. So if you harvest a corn/crop and whole plants, only the corn/crop yield will be provided. If you harvest whole plants and foliage, only the yield for whole plants will be provided. The order of the value is corn/crop (most valuable) → whole plants → foliage.

  • The value yieldPerHa refers to the yield per hectar of the harvestingAreaInHectar. So the result

      "yieldPerHa": {
    "unit": "kg",
    "value": 1738.269,
    "type": "BOOKED"
  },
  "harvestingAreaInHa": 0.6564

    means 1738.269 kg/ha of the most valuable yield was harvested on total harvesting area of 0.6564 hectar. That is a total yield of 1141 kg of the most valuable yield on this field in the harvest year.

  • The value harvestingAreaInHectar provides the total area that was harvested to get the yield from in the year. For instance if a field that doesn’t change its shape over the whole harvest year is harvested two times, and the fields size is 0.3282 ha, harvestingAreaInHectar will be two times the fields size = 0.6564 ha.

by date

An external partner can retrieve information about crop cultivation for a company on any specified date. Given a date it returns information about the fields and the cultures (=crops) grown on them at that date. Fields without a crop at the given date are excluded.

The crops grown can also be retrieved by a query using a list of field id's besides a date as query parameters, in which case the information will only be returned for the specified fields.

Fields

An external partner can retrieve, create and update a list of field objects of the company in a certain harvest year. Only valid and undeleted fields are included (at the time of request), no historical fields.

Fields can be invalid because of duplicate or missing keys (e.g. number) or because of corrupt geometries. Fields can be filtered by usage (cropland, grassland, etc.) and they can also be retrieved by a query using known farm IDs or field IDs as query parameters. The fields' geometries can be explicitly excluded or included.

Fields can only be created for the main farm ID and updated when belonging to the company. Updating the validity is currently not possible.

Fields can be merged or split by the user due to considerations in his production process. A single field can only have one culture (=crop) at a time, so in some cases the user will split fields into smaller parts for one or more harvest years and typically merge them again afterwards. The result of splitting is always two new fields with one predecessor. A split field can be split again, so there can be numerous new fields that were derived from one initial field. In the case of merging fields there is always one new field with two predecessors. Merged fields can be merged again with others, so there can always be a new field derived from multiple predecessors. Important note: The current total acreage of fields is not affected by splitting and merging!

As far as the harvest year is concerned, fields that were split or merged after the 1st of July belong to the following harvest year, because cultures sown after 1st July will typically not be harvested before the subsequent year.

Field cards

For a given harvest year, the partner can retrieve all fields that were cultivated in that year. This list can be used to request field cards. There are two options for requesting field cards:

  • A field card per harvest year and field
  • A field card per crop and field. If several crops were harvested in a year, the user can request a field card for each crop.

If the user has harvested the same crop several times in a row - then we have one field card. When the user has harvested different crops in a row - then we have multiple field cards per harvest year.

Guidance lines

A guidance line (also called reference line) is a geometric line inside a field's geometry. Every guidance line is connected to a specific field (but there can also be multiple guidance lines connected to a field). It determines one track to be used by the GPS guidance system of a machine while working the field.

Since a guidance line describes only one track, the terminal or task controller of the machine multiplies the line by creating further lines which are parallel to the guidance line. It is set at the terminal and determined by the machine's working width (and an overlap if desired).

We currently support the following types of guidance lines:

  • A – B lines: straight line determined by two points (A and B)
  • Contour lines: curved line determined by starting point A, any number of guidance points in between, and end point B

As a guidance line can be shorter than the field it is on, the machine's terminal or task controller extrapolates the guidance line beyond the start and end points in straight lines.

The following example shows the field's geometry in white/blue, the guidance line in yellow and the lines created by a terminal in green.

Guidance lines
Map data provided by Google.

Through the API an external user can

  • Create a guidance line (requires the field ID and guidance line ID)
  • Delete a guidance line (requires the field ID and guidance line ID)
  • Retrieve a single guidance line (requires the field ID and guidance line ID)
  • or retrieve all guidance lines connected to a field (requires the field ID)

Cultures (= crops)

An external partner can retrieve a list of crop objects of the platform's catalogue data. This is not limited to the account's list of crops (defined by active seeds) but returns the entire catalogue of crops used in the platform.

Seeds

An external partner can retrieve a list of seed objects of the company. By default, only active seeds (at the time of request) are included. Seeds can be inactive, when they are no longer used but were once activated by the user.

Seeds can also be retrieved by a query using known seed IDs as parameters.

Fertilizers

An external partner can retrieve a list of fertilizer objects of the company. By default, only active fertilizers (at the time of request) are included. Fertilizers can be inactive, when they are no longer used but were once activated by the user.

Fertilizers can also be retrieved by a query using known fertilizer IDs as parameters.

Farms

An external partner can retrieve a paged and sorted list of farm objects of the company. By default, only valid and active farms are delivered. A farm can be inactive when it is no longer in use but was once active. And it can be invalid because of duplicate or missing keys (e.g. number). Invalid farms are not returned.

Forage

An external partner can retrieve a paged list of forage objects of the company. By default, only active and valid forages (at the time of request) are included. Forages can be inactive, when they are no longer used but were once activated by the user. And they can be invalid because of duplicate or missing keys (e.g. number). Invalid forages are not returned.

Images

Machines can have an image. The API allows to upload an image to the machine. The image must be square. The API supports to crop an image out of a larger image.

Persons

An external partner can retrieve a paged list of person objects of the company. By default, only active and valid persons (at the time of request) are included. Persons can be inactive, when they are no longer used but were once activated by the user. And they can be invalid because of duplicate or missing keys (e.g. number).

Persons can also be retrieved by a query using known persons IDs as parameter.

An external partner can also create and update person objects in 365FarmNet.

Machines

An external partner can retrieve a paged and sorted list of machine objects of the company. By default, only active machines are returned. A machine can be marked as inactive by the user. Inactive typically means the machine is no longer in use by the user.

Machines can also be retrieved by a query using known machine IDs as parameter.

An external partner can also create, update and delete machine objects in 365FarmNet. With the validate endpoint it can be checked if the machine parameters are correct without saving. The default endpoint returns a machine filled with default values.

Each machine has a number which must be unique within the company account. The same applies for the serial number.

The manufacturers endpoint returns a list of all manufactures that can be used for a machine.

Each machine can have one image assigned. The machine object itself returns the link to the image.

Operations/Tasks

Getting operations

You can get completed harvest and sowing operations for a specific time range and a set of fields.

Operations can contain of several attributes like fields, harvest products, seeds, machines, persons, or notes.

Format:

  • Exchange-Format (365FarmNet proprietary format)

Sending operations

You can send completed and planned operations of all types for a specific time range and set of fields.

We differentiate between 6 types:

  • CULTIVATING
  • HARVESTING
  • SOWING
  • PLANTPROTECTING
  • TILLING
  • FERTILIZING

Operations can contain of several attributes like fields, harvest products, plant protectants, fertilizers, seeds, machines, persons, attachments (prescription maps, counter values e.g. fuel) or notes.

Formats:

  • Exchange-Format (365FarmNet proprietary format)
  • ISO 11783-10 (see https://www.iso.org/obp/ui/#iso:std:iso:11783:-10:ed-2:v1:en) - only completed operations

Geodata

An external partner can retrieve geo-referenced resources which are available in the mapcenter (map catalogue) of 365FarmNet (https://devcon.365farmnet.com/mapcenter). Geo-referenced resources include vector (point, line, polygon) or raster (geotiff, etc.) data with a spatial reference (e.g. coordinates). Therefore, the data could be visualized on a map. The actual data type stored in the payload is specified by the media type in the metadata section of the resource.