FieldStat Developer Documentation

Welcome to the developer documentation for FieldStat.

FieldStat provides per-field growers’ data combined from AI models and public sources for major ag markets on the whole-country level. This documentation will help you understand how to integrate your application with our API.

API Description

The FieldStat API implements the endpoints to provide:

Several endpoints implement pagination to ensure fast response when a lot of data is obtained. Make sure to consider it to retrieve all the results.

The maximum allowed area of a bbox to request fields is 1000 square kilometers, but for optimal performace we recommend to use a smaller bbox, preferrably not larger than 100 square kilometers. This corresponds to a map zoom level of around 13.

For all the returned geometries the coordinate system is EPSG:4326, and the area is always in square meters.

OpenAPI Specifications

For detailed API specifications, please refer to our OpenAPI documentation. For programmatic access, please use openapi.json file.

Authentication

To get started with the FieldStat API, you'll need to authenticate using OAuth2 client credentials. You will obtain your pair of credentials (client_id and client_secret) from the FieldStat team.

Having the credentials, you can obtain an access token using the /oauth2/token endpoint. This token is further used for authentication when calling the other endpoints. Please find an example of obtaining and using such a token in the Python code below.

The OAuth2 access token is temporary. When the access token expires, you will get the HTTP response code 401. After that you need to get a new access token using the same pair of credentials (client_id and client_secret).

Authentication example

The following Python code gives an example of obtaining an access token. The prerequisites to run this code are

import requests

# Replace these with your client ID and client secret
client_id = "your_client_id"
client_secret = "your_client_secret"

# OAuth2 token endpoint
token_url = "https://api.fieldstat.ai/oauth2/token"

# Request payload
payload = {
    "grant_type": "client_credentials",
    "scope": "api:read",
}

# Make the request to obtain the token
response = requests.post(token_url, data=payload, auth=(client_id, client_secret))
response_data = response.json()

# Extract the access token
access_token = response_data["access_token"]
print(f"Access Token: {access_token}")

API call example

Once you have the access token, you can make authenticated API calls. Here’s an example of how to retrieve a list of regions:

import requests

# Replace this with the access token you obtained
access_token = "your_access_token"

# API endpoint for retrieving available regions list
api_url = "https://api.fieldstat.ai/api/regions"

# Set the authorization header
headers = {
    "Authorization": f"Bearer {access_token}",
}

# Make the request
response = requests.get(api_url, headers=headers)
regions = response.json()

# Print the retrieved regions
print(regions)

Pagination

The FieldStat APIs use cursor-based pagination to manage large datasets efficiently. You can specify the number of records to return per request and the cursor position from which to continue fetching records.

Parameters

Response

The API returns a JSON object with the following structure:

{
    "data": [],
    "pagination": {
        "count": 0,
        "cursor": null
    }
}

with the following attributes:

Example: fetching all fields in bbox

Below is an example of how to fetch all records from an API using the described pagination mechanism. This example specifically demonstrates fetching fields from the /fields API:

import requests


def fetch_all_records(url: str, params: dict, headers: dict) -> list[dict]:
    # Start with an empty list records to collect all fetched data
    records = []
    cursor = 0
    page_size = 100

    # Continuously fetch data from the API until the cursor is null
    while True:
        # Set pagination params
        request_params = params.copy()
        request_params.update({"cursor": cursor, "page_size": page_size})

        # Make the request
        response = requests.get(url, params=request_params, headers=headers)
        response_json = response.json()

        # Extend the records list with the new data.
        records.extend(response_json["data"])

        # Update the cursor value from the response for the next iteration
        cursor = response_json["pagination"]["cursor"]

        # If the cursor is null, exit the loop
        if cursor is None:
            break

    return records


# Replace this with the access token you obtained
access_token = "your_access_token"

# API endpoint for retrieving fields
api_url = "https://api.fieldstat.ai/api/fields"

# Set /fields API params
api_params = {
    "bbox": "4.856322,52.445675,5.163747,52.57364",
}

# Set the authorization header
api_headers = {
    "Authorization": f"Bearer {access_token}",
}

# Fetch all fields
fields = fetch_all_records(api_url, api_params, api_headers)

# Print the retrieved fields
print(fields)

Support

Thank you for using FieldStat! If you have any questions or need further assistance, please don't hesitate to reach out to our support team