groundtruth-ag

Python client for the BRD Groundtruth API — read your own farm data (fields, weather, irrigation scheduling, soil health, yield history, equipment, market prices) from your own scripts.

This is a read-only v1: nothing here creates or modifies data in your account.

Install

pip install groundtruth-ag

Quickstart

Generate a personal API key at bishopresearch.com → Dashboard → Settings → API Keys, then:

from groundtruth_ag import Client

client = Client(api_key="brd_live_...")
# or: export BRD_API_KEY=brd_live_... and just call Client()

for field in client.fields.list():
    forecast = client.fields.weather(field["id"])
    schedule = client.fields.irrigation(field["id"], days=7)
    print(field["name"], schedule["schedule"])

Resources

Full request/response shapes: https://developer.bishopresearch.com and the interactive reference at https://bishopresearch.com/api/v1/docs.

Errors

Every non-2xx response raises a typed exception, all subclasses of BRDAPIError:

from groundtruth_ag import Client, NotFoundError, RateLimitError, AuthenticationError

client = Client()
try:
    client.fields.get(999999)
except NotFoundError:
    print("no such field")

429s and 5xx responses are retried automatically (2 retries, exponential backoff) before an exception is raised — RateLimitError/ServerError mean retries were already exhausted.

Context manager

with Client(api_key="brd_live_...") as client:
    print(client.me())
# connection closed automatically

Development

pip install -e ".[test]"
pytest

Design notes

• Built on httpx. A sync client only for now; an AsyncClient mirroring the same resource classes on httpx.AsyncClient is a natural follow-on once there's demand, not built speculatively here.
• Auth is a bearer token (Authorization: Bearer <key>) whether it's a personal API key today or an OAuth access token in the future — the transport layer doesn't care which, so a future OAuth flow wouldn't require a breaking change to this library's public API.
• No pagination: every v1 resource returns a small, complete list (a farm's fields, not millions of rows), so none was added.