Send your farmers and plot boundaries. We check them against our records, run the deforestation analysis, and return a risk result for each plot.
https://YOUR-DOMAIN/api/v1/. All requests and responses are JSON over HTTPS. Pricing, tokens and daily limits are set by the administrator for your plan.Send your key in the x-api-key header. Keys are created by the administrator under API & partners and are shown once. Keep them secret and never put them in browser code.
x-api-key: fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Starts a verification. Up to 2000 plots per request.
| Field | Type | Notes |
|---|---|---|
farmers[] | array | Required. One entry per farmer. |
farmers[].ref | string | Your own farmer id. Returned to you. |
farmers[].name | string | Recommended. |
farmers[].national_id | string | Strongly recommended. Used to recognise people we already know. |
farmers[].plots[].ref | string | Your plot id. |
farmers[].plots[].geometry | GeoJSON | Polygon or Point, coordinates as [longitude, latitude]. Or send lat and lng instead. |
farmers[].plots[].area_ha | number | Hectares. |
crop, variety, season | string | Optional context, e.g. Coffee, Robusta. |
contribute | boolean | true means you agree that verified records may be added to our database. Default false: nothing is stored beyond your own submission. |
{
"contribute": true, "crop": "Coffee", "variety": "Robusta",
"farmers": [{
"ref": "F-100", "name": "Jane Example", "national_id": "CF85000000000A",
"plots": [{ "ref": "P-1", "area_ha": 1.2,
"geometry": { "type": "Polygon", "coordinates": [[[31.6001,-0.1501],[31.6010,-0.1501],[31.6010,-0.1510],[31.6001,-0.1510],[31.6001,-0.1501]]] } }]
}]
}
Response 202 (verification started) or 200 (everything was already known):
{ "code": "analysis_queued",
"data": { "submission": "SUB-261105-A1B2C3", "status": "verifying",
"matched": [ { "plot_ref": "P-9", "our_plot_id": "PLT-000412", "our_farmer_id": "FRM-000230", "match": "plot_overlap",
"message": "Already in our database. Use these ids instead of creating new records." } ],
"to_verify": 1, "errors": [], "tokens_to_charge": 1 } }
Poll every 5 to 10 seconds until status is completed (or failed). You can only see your own submissions.
{ "code": "analysis_completed",
"data": { "submission": "SUB-261105-A1B2C3", "status": "completed", "matched_plots": 1, "verified_plots": 1,
"result": { "verified": [ { "plot_ref": "P-1", "farmer_ref": "F-100",
"risk_perennial_crop": "low", "risk_annual_crop": "low", "risk_timber": "low", "overall": "low",
"our_plot_id": "PLT-000501", "our_farmer_id": "FRM-000311", "note": "Added to our database. Use these ids from now on." } ],
"matched": [], "errors": [] } } }
Risk values: low, more_info_needed, high. overall is the risk for the crop type chosen by the administrator (perennial crops, such as coffee, by default). The our_*_id fields appear only when you set contribute to true.
Before anything is verified we look for each plot in our records: a farmer with the same national_id, or any plot whose location is within about 20 metres. A match is not added again and is not charged. We return our IDs in matched. Please store them against your own records and use them in future requests.
Only data you contributed (with contribute: true) is ever added to our database, and it is linked back to your references.
/verify.php or /status.php counts toward your daily request limit. Response headers X-RateLimit-Limit and X-RateLimit-Remaining show where you are. At the limit you get 429.tokens_to_charge and is charged when the job completes. A request that cannot be covered returns 402 before any work starts.| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_json / invalid_request | Body is not valid or has no farmers. |
| 401 | unauthorized | Missing, wrong or revoked key. |
| 402 | insufficient_tokens | Top up tokens. |
| 403 | api_disabled | API is not enabled for your plan. |
| 404 | not_found | Unknown submission reference. |
| 413 | too_large | More than 2000 plots. |
| 429 | rate_limited | Daily limit reached. |
| 502 | verification_unavailable | Analysis service unreachable. Nothing was charged. Retry later. |
Per-plot problems (for example a missing geometry) do not fail the whole request. They are listed in errors.
curl -X POST https://YOUR-DOMAIN/api/v1/verify.php \
-H "x-api-key: $FISKON_KEY" -H "Content-Type: application/json" \
-d @submission.json
curl "https://YOUR-DOMAIN/api/v1/status.php?ref=SUB-261105-A1B2C3" -H "x-api-key: $FISKON_KEY"
import os, time, requests
BASE, H = "https://YOUR-DOMAIN/api/v1", {"x-api-key": os.environ["FISKON_KEY"]}
sub = requests.post(f"{BASE}/verify.php", headers=H, json=payload, timeout=60)
sub.raise_for_status(); ref = sub.json()["data"]["submission"]
while True:
r = requests.get(f"{BASE}/status.php", headers=H, params={"ref": ref}, timeout=60).json()
if r["data"]["status"] in ("completed", "failed"): break
time.sleep(8)
print(r["data"]["result"])
const BASE = "https://YOUR-DOMAIN/api/v1", H = { "x-api-key": process.env.FISKON_KEY, "Content-Type": "application/json" };
const sub = await (await fetch(`${BASE}/verify.php`, { method: "POST", headers: H, body: JSON.stringify(payload) })).json();
const ref = sub.data.submission; let r;
do { await new Promise(s => setTimeout(s, 8000)); r = await (await fetch(`${BASE}/status.php?ref=${ref}`, { headers: H })).json(); }
while (!["completed", "failed"].includes(r.data.status));
console.log(r.data.result);
$ch = curl_init("https://YOUR-DOMAIN/api/v1/verify.php");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("FISKON_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode($payload)]);
$res = json_decode(curl_exec($ch), true); $ref = $res["data"]["submission"];
Ready-to-run versions are in docs/samples/.