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.

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

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

The API enbles an external partner to send planned bookings or completed bookings to 365FarmNet and in the future will also allow sending the same from 365FarmNet to an external partner.

Minimal required information:

Type of activity (tillage, seeding, spraying, spreading, harvesting or types created by the user)

  • Reference to one or multiple field(s)
  • In case of activities that involve one or multiple physical input(s) (seeds, crop protection chemicals, fertilizers…) a reference to these inputs is required

Optional information:

  • Involved machines
  • Involved persons
  • Attachments (notes, application map…)
  • Amount of physical inputs applied

Formats:

  • Exchange-Format (365FarmNet proprietary format)
  • ISOXML