ProPlanta Recommendation API

A single HTTPS endpoint that turns plot & soil data into a fertilizer recommendation. This guide covers everything you need to integrate.

Overview

You send one or more plots (soil analysis, crop, history) in a JSON request; the service runs the agronomic model and returns a recommendation report for each plot. You authenticate with a token we issue to you — there is no sign-up or login flow on your side.

The integration is a single call:

• POST your JSON to /pp
• Put your token in the Authorization header
• Read the recommendation text back from the response body

Authentication

Every request must include the token we provide, sent verbatim in the Authorization header. Do not add a Bearer prefix.

Authorization: eyJhbGciOiJIUzI1NiIs...your-token...

The endpoint

Request body

The body has two parts: userinfo (the grower/client this recommendation is for) and plotinfo (an array — one object per plot). You may submit several plots in a single request; each is processed independently.

{
  "userinfo": {
    "username": "Példa Gazda Kft.",
    "regid":    "1002456789",
    "address":  "7400 Kaposvár, Fő utca 1.",
    "phone":    "+36 30 123 4567",
    "email":    "iroda@pelda-gazda.hu"
  },
  "plotinfo": [
    {
      "plotname":      "Kaszásmajor",
      "mepar":         "ABCD1-K-12",
      "area":          12.4,
      "soil":          1,
      "samplingdate":  "2024-09-23",
      "humus":         3.1,
      "phkcl":         7.2,
      "alp2o5":        120,
      "alk2o":         145,
      "harvestyear":   2025,
      "plant":         "kukorica",
      "plantid":       1111,
      "planttype":     1,
      "plannedyield":  7.3
    }
  ]
}

Client fields (userinfo)

Plot fields (each item in plotinfo)

Grouped by topic. Types: string, number (decimals allowed), integer (whole numbers / codes).

Plot identity

Soil sample results

Crop & production

Leaf analysis & orchard/vineyard (perennials)

Pre-crop

Nutrients applied this year

Organic matter & amendment history

Success response

200 OK — the body is a plain-text report (not JSON), with one section per plot, in the order you sent them. Content type is text/plain.

Ask us for a sample report for your crop set so you can build your parser against the exact output layout.

Status codes

Errors & retries

• 403 → your token is expired/invalid. Request a fresh one and retry. Do not retry with the same token in a tight loop.
• 400 → a payload problem (malformed JSON). Retrying unchanged will fail again — fix and resend.
• 500 → transient server issue. Retry a few times with exponential backoff (e.g. 1s, 4s, 10s). If it keeps failing, contact us.
• 200 with error: in a section → that one plot couldn't be computed (often bad/contradictory inputs for that plot). Check the plot's data; other plots in the same request still succeeded.

Example — cURL

curl -X POST https://company.proplanta.atk.hu/pp \
  -H "Authorization: $PROPLANTA_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Example — Python

import requests

resp = requests.post(
    "https://company.proplanta.atk.hu/pp",
    headers={"Authorization": TOKEN, "Content-Type": "application/json"},
    json={
        "userinfo": {"username": "Példa Gazda Kft.", "regid": "1002456789"},
        "plotinfo": [{
            "plotname": "Kaszásmajor", "area": 12.4, "soil": 1,
            "humus": 3.1, "phkcl": 7.2, "alp2o5": 120, "alk2o": 145,
            "harvestyear": 2025, "plant": "kukorica", "plantid": 1111,
            "planttype": 1, "plannedyield": 7.3,
        }],
    },
    timeout=60,
)

if resp.status_code == 403:
    raise SystemExit("Token expired or invalid — request a new one.")
resp.raise_for_status()          # raises on 400/404/500
report = resp.text               # plain-text report, one section per plot
if "error: recommendation failed" in report:
    print("Warning: at least one plot failed — inspect the report.")
print(report)

Example — Node.js

const res = await fetch("https://company.proplanta.atk.hu/pp", {
  method: "POST",
  headers: { "Authorization": process.env.PROPLANTA_TOKEN,
             "Content-Type": "application/json" },
  body: JSON.stringify({
    userinfo: { username: "Példa Gazda Kft.", regid: "1002456789" },
    plotinfo: [{
      plotname: "Kaszásmajor", area: 12.4, soil: 1,
      humus: 3.1, phkcl: 7.2, alp2o5: 120, alk2o: 145,
      harvestyear: 2025, plant: "kukorica", plantid: 1111,
      planttype: 1, plannedyield: 7.3,
    }],
  }),
});

if (res.status === 403) throw new Error("Token expired or invalid.");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const report = await res.text();   // plain-text report
console.log(report);