Skip to main content

Introduction

The AgroAPI is the API behind FarmAI. If you have access to this API you can programatically read and write information in your FarmAI organization.
It can:

  • Let you manage farms, fields, cropzones, activities.
  • Let you download various vegetation indexes (e.g NDVI, NDMI, EVI)
  • Let you download soil analysis samples

Getting Started​

Get an API token​

First you'll want to contact support@listenfield.com in order to get an AgroAPI token.
Our API tokens are simple opaque api tokens that you need to put in http headers as Authorizaton Bearer <TOKEN>.

caution

This token is a server token and should not be shared and not be accessible by client devices. If you think your token has been compromised contact support@listenfield.com

Refresh Token / Access Tokens​

This is likely that Listenfield gave you an AgroAPI refresh token. As this token does not expires it is not supposed to be used directly. Instead this refresh token should be used to request a short lived access token. The AgroAPI follows a similar model as the OAuth credentials flow.
You have been given both a client_id and a client_secret. Example:

{
  "client_id": "2d001af5-13a7-457f-bc8c-42f8133be6c9",
  "client_secret": "MJG2342hEmm3m8Gc7VzRcfjxaYz5985Uu1pJ"
}

Then to get the short lived token you should call /token endpoint.

import axios from "axios";

axios.post("https://agro.api.listenfield.com/token", {
  grant_type: "client_credentials",
  client_id: "CLIENT_ID",
  client_secret: "CLIENT_SECRET",
});
API Response
{
    "access_token": "szHy6rucDP8N26U1fHwLzWhpw42S2RLFPkrgP",
    "token_type": "Bearer",
    "expires_in": 21600,
    "created_at": 1664350938
}

Then you can use this access token as a Bearer token in your calls to the AgroAPI.
You can refer to the expires_in key to know the number of seconds left until that token expires (here 6 hours).

Architecture​

It's important to understand the concepts used in the AgroAPI in order to use it properly.

Organization​

An Organization is an entity which follow farms. A same farm can be followed by many organizations. If an organization follows a farm they can see their fields, their activities and the list of farmers on the farm.

Farm​

A farm is owned by farmers (users). You can have an infinite number of farmers (users) in the same farm. And a farmer can join or be invited in many farms.

Field​

A farm has one or many fields. A field has polygon coordinates (GeoJSON). A field has many cropzones.

Cropzone​

A cropzone is part of a field assigned to a specific crop. So in the same field you could have 2 cropzones, one covering 50% of the field with Banana as crop, and the other one covering 50% for oranges.

Activity​

An Activity in farm ai is a farming activity. It's usually rattached to a cropzone. Activities have types, which come from a predefined list return by the AgroAPI GET /activity_types endpoint.

Follow / Invitations​

An organization can follow farms. When an organization follow a farm they can see all their fields, their list of farmers, and their activities.
The farm need to accept a follow request in order for this to be possible.

An invitation is different. An organization or a farm can invite a user to join their organization / farm. You can send an invitation and if the user accept the invitation they are now part of the organization / farm.
As of right now there is no particular user roles inside farms and organizations, all users who joined a farm / organization will have the same rights.

Units​

The AgroAPI is storing everything as m2. You have to do the conversions on your side if needed.

Area size: m2
Harvest/Production: in tons (1000kg).
Yield: tons/m2

caution

The format of coordinates is [longitude, latitude] and NOT [latitude, longitude].

Pagination​

A lot of AgroAPI endpoints support pagination.
You can pass a page and a items parameter. Page starts from 1. Items is the number of elements per page (default: 50, max: 100).
In the HTTP headers of the response you'll find:

Total-Count: 75
Total-Pages: 2
Page-Items: 50
Current-Page: 1

Total-Count is the total of items in the database matching your query.
Total-Pages is the total number of pages.
Page-Items is the number of items in the current response.
Current-Page is the current page number.

Graph​

graph TD Organization(Organization)-->Farm(Farm) Organization-->Users(Users) Farm-->Users Farm-->Field1(Field 1) Farm-->Field2(Field 2) Field1 --> Cropzone1(Cropzone 1) Field1 --> Cropzone2(Cropzone 2) Cropzone2 --> Activity1(Activity 1)