Geo-Analyse über die API

Übersicht

Sie senden die Geometrie einer Parzelle, die Entwaldungsanalyse startet automatisch, und Sie lesen das Ergebnis als JSON und laden den Parzellenbericht als PDF. Ein Artikel oder Lieferant ist dafür nicht nötig — eine Parzelle mit Rohstoffgruppe genügt.

Schritt	Endpunkt
Optional: Geometrie prüfen	`POST /api/v1/plots/validate`
Parzelle anlegen	`POST /api/v1/plots`
Status und Ergebnis abfragen	`GET /api/v1/plots/{id}?fields=analysisStatus,analysis`
Parzellenbericht herunterladen	`GET /api/v1/plots/{id}/report`

Berechtigungen

Schlüsselmechanismus, Basis-URL und die allgemeinen Statuscodes stehen in der Einführung; wie Sie einen Schlüssel anlegen, steht unter Einstellungen → API-Schlüssel. Parzellen gibt es nur im EUDR-Modul. plots:write deckt alles ab; plots:read genügt, um das Ergebnis zu lesen und den Bericht herunterzuladen.

In einem Kunden-Workspace antwortet der Bericht mit 403 und EUDR compliance module is not enabled, wenn das EUDR-Modul für den Benutzer, für den der Schlüssel handelt, nicht aktiviert ist (persönlicher Schlüssel: sein Inhaber; Unternehmensschlüssel: der ranghöchste aktive Benutzer des Workspace). Das Ergebnis-JSON hat diese Prüfung nicht.

Parzelle anlegen

POST /api/v1/plots legt eine Parzelle an und startet ihre Analyse. Alle Felder stehen in der Endpunkt-Referenz; für eine Integration wichtig:

geojson ist Pflicht (siehe Geometrie).
commodityGroup ist Pflicht, wenn Sie keine supplierArticleIds senden: eine von cattle, cocoa, coffee, oil_palm, rubber, soya, wood. Die API akzeptiert außerdem non_relevant (steht in der Fehlermeldung); für eine Parzelle, die analysiert werden soll, nicht senden. Mit supplierArticleIds wird die Gruppe dann aus den Artikeln abgeleitet.
Bei wood ist species Pflicht — je Eintrag commonName und scientificName.
Tragen Sie Ihre eigene Parzellenreferenz in name ein (siehe Idempotenz).
country (ISO 3166-1 Alpha-2, z.B. BR): Ohne Land (oder mit einem nicht auflösbaren Wert) greift das Überspringen für Länder mit geringem Risiko nie; die Parzelle wird immer analysiert.

Geometrie

Erlaubt sind Polygon, MultiPolygon, Point und MultiPoint — als bloße Geometrie oder als Feature. Koordinaten in WGS84, Reihenfolge [Längengrad, Breitengrad]; eine Höhenangabe (dritter Wert) wird angenommen, aber nicht gespeichert. Koordinaten außerhalb von Längengrad ±180 / Breitengrad ±90 werden abgelehnt; es wird nichts gespeichert.
Eine Anfrage legt eine Parzelle an. Eine FeatureCollection wird abgelehnt — senden Sie jedes Feature als eigene Anfrage. Andere Typen (LineString, GeometryCollection, …) werden ebenfalls abgelehnt.
Ist size angegeben, ist ein Point oder MultiPoint nur bis 4 ha zulässig (20.000 ha, wenn commodityGroup cattle ist); darüber verlangt die EUDR ein Polygon. Ohne size gibt es keine Flächenprüfung.

Qualitätsprüfungen

Vor dem Speichern führt die API dieselben Geometrieprüfungen durch wie der Import in der App und speichert das Ergebnis:

Prüfung	Was passiert
Koordinaten	Auf 6 Nachkommastellen gerundet; Höhenangabe entfernt; aufeinanderfolgende doppelte Punkte entfernt; offene Ringe geschlossen; Umlaufrichtung der Ringe vereinheitlicht
Löcher (innere Ringe)	Entfernt — Warnung `POLYGON_HOLES_REMOVED`
Selbstüberschneidung	Repariert, wenn die Reparatur die Fläche um höchstens 2 % ändert (das Ergebnis kann ein `MultiPolygon` sein) — Warnung `POLYGON_SELF_INTERSECTION_REPAIRED`; ein Loch, das die Reparatur einschließt, wird danach wie jedes Loch entfernt. Sonst abgelehnt
Genauigkeit	Gezählt nach den Ziffern, wie sie in der Anfrage stehen (`-47.060100` zählt als 6); maßgeblich ist der Wert mit den wenigsten Nachkommastellen (Löcher und Höhenangabe zählen nicht). 6 oder mehr: in Ordnung; 5: Warnung `COORDINATE_PRECISION_BORDERLINE`; 4: Warnung `COORDINATE_PRECISION_LOW`; 3 oder weniger: abgelehnt

Wird ein Loch entfernt – auch eines, das erst die Reparatur einer Selbstüberschneidung einschließt –, wird die ausgeschlossene Fläche Teil der Parzelle: Die Parzelle wird größer. Die API vertauscht Breiten- und Längengrad nie. Die Antwort beim Anlegen nennt die Codes oben in warnings ([{ "code": … }]); Rundung, entfernte Höhenangabe, entfernte doppelte Punkte sowie geschlossene oder umgedrehte Ringe werden nicht genannt. Bei einer deduplizierten Antwort ist warnings immer leer, weil diese Anfrage nichts gespeichert hat.

Idempotenz

Senden Sie dieselbe Parzelle erneut — gleicher name, gleiches country, gleiche Geometrie (verglichen nach den Qualitätsprüfungen) und gleiche supplierArticleIds —, legt die API keine zweite Parzelle an und startet keine zweite Analyse; sie antwortet mit der gespeicherten Parzelle und "deduplicated": true. Name und Land werden ohne Rücksicht auf Groß-/Kleinschreibung, Leerzeichen am Anfang und Ende sowie mehrfache Leerzeichen verglichen. Andere Felder einer Wiederholung, etwa commodityGroup oder size, werden nicht übernommen. Die Antwort enthält "updated": true, wenn Erzeuger, Produktionsdaten oder Holzarten der Wiederholung übernommen wurden, sonst false; wurde eine neue Parzelle angelegt, fehlt das Feld. Auch die Wiederholung einer Parzelle, die vor Einführung dieser Prüfungen gespeichert wurde, wird erkannt: Verglichen wird zusätzlich die Geometrie genau so, wie sie gesendet wurde.

Geometrie prüfen, ohne eine Parzelle anzulegen

POST /api/v1/plots/validate nimmt denselben Body wie das Anlegen und führt dieselben Prüfungen durch, schreibt aber nichts — keine Parzelle, keine Analyse (Probelauf). plots:read genügt, und commodityGroup ist optional. Eine Anfrage, die das Anlegen mit einem code ablehnen würde, erhält 200 mit valid: false und diesem Code; ein Body, der kein JSON ist, erhält 400. valid sagt, ob das Anlegen die Anfrage annehmen würde, abgesehen von den unten unter „Nicht geprüft” genannten Punkten. Für ein Polygon mit einem Loch, mit 6 Nachkommastellen geschrieben:

{
  "valid": true,
  "errors": [],
  "warnings": [{ "code": "POLYGON_HOLES_REMOVED" }],
  "precision": { "digits": 6, "class": "ok" },
  "geometry": { "type": "Polygon", "coordinates": [[[-47.060123, -21.181934], [-47.058531, -21.181934], [-47.058531, -21.180245], [-47.060123, -21.180245], [-47.060123, -21.181934]]] },
  "measuredAreaHa": 3.1
}

geometry ist die Geometrie, die das Anlegen speichern würde, measuredAreaHa ihre Fläche — 3,1 ha statt der 2,68 ha des Polygons mit Loch; null bei Punkten. Bei valid: false enthält errors den code und die message, mit denen das Anlegen antworten würde, geometry und measuredAreaHa sind null, und precision ist null, wenn die Anfrage abgelehnt wurde, bevor die Genauigkeit gemessen war. Der Probelauf gibt der Flächengrenze für Punkte und einer ungültigen size einen Code (plot_point_area_too_large, plot_size_invalid); das Anlegen antwortet darauf ohne Code. Nicht geprüft wird, ob commodityGroup ohne supplierArticleIds fehlt (das Anlegen antwortet mit plot_commodity_group_required), ob die supplierArticleIds zu Ihrem Unternehmen gehören und ob dieselbe Parzelle schon existiert.

Status abfragen

`analysisStatus`	Bedeutung
`pending`	Angelegt oder Geometrie geändert; Analyse noch nicht gestartet
`in_progress`	Analyse läuft
`completed`	Analyse abgeschlossen; `riskLevel` ist `LOW`, `MODERATE` oder `HIGH`
`failed`	Die Analyse konnte nicht durchgeführt werden, oder die Parzelle hat die Plausibilitätsprüfung nicht bestanden (`riskLevel: INVALID`), z.B. wegen Überlappung mit Gewässern oder Siedlungsflächen
`exempt`	Das angegebene Produktionsende (`productionDateTo`) liegt am oder vor dem 31. Dezember 2020; es wird keine Analyse durchgeführt
`skipped`	Die Parzelle liegt in einem EUDR-Land mit geringem Risiko, und Geoanalyse für Länder mit geringem Risiko ist für Ihr Unternehmen nicht aktiviert (siehe Einstellungen)

Fragen Sie alle 15 bis 30 Sekunden ab, solange der Status pending oder in_progress ist. Die App setzt für diese Endpunkte kein Rate-Limit je Schlüssel. Ist die Analyse failed oder skipped, können Sie die Parzelle in der App über Neu analysieren erneut analysieren lassen (siehe Parzellen verwalten). Nach Neu analysieren behält der Status seinen bisherigen Wert, bis die Analyse startet.

Ergebnis lesen

analysis enthält das zuletzt gespeicherte Ergebnis. Es ist null, wenn nie eines gespeichert wurde oder nachdem die Geometrie geändert wurde. Während eine erneute Analyse läuft (in_progress) oder nachdem eine erneute Analyse fehlgeschlagen ist, kann es noch das vorherige Ergebnis enthalten — vergleichen Sie assessedAt. Die Texte sind Englisch und wortgleich mit dem Parzellenbericht.

{
  "analysisStatus": "completed",
  "analysis": {
    "riskLevel": "LOW",
    "assessedAt": "2026-09-29T09:14:03.000Z",
    "conclusion": "The recorded analysis did not establish post-cutoff deforestation or forest degradation for this plot.",
    "limitations": [],
    "evidence": [
      { "dataset": "JRC GFC 2020", "measurementStatus": "Recorded value; dataset plot coverage not stored", "observation": "Forest baseline value: 62.4% of plot", "relevance": "Forest baseline at cutoff" },
      { "dataset": "Hansen GFC", "measurementStatus": "Measured", "observation": "Post-2020 loss: 0.0% of JRC baseline forest", "relevance": "Tree-cover loss after cutoff" }
    ]
  }
}

Weitere riskLevel-Werte können hinzukommen; behandeln Sie einen unbekannten Wert als prüfbedürftig. Die Namen in evidence[].dataset sind stabil (JRC GFC 2020, Hansen GFC, GFW alerts, JRC TMF AnnualChange und JRC GFT 2020 nur bei wood); measurementStatus, observation und relevance sind für Menschen gedacht, ihr Wortlaut kann sich ändern — werten Sie sie nicht maschinell aus.

Risikostufen

`riskLevel`	`conclusion`	Bedeutung
`LOW`	The recorded analysis did not establish post-cutoff deforestation or forest degradation for this plot.	Die aufgezeichnete Analyse hat für diese Parzelle Entwaldung oder Walddegradation nach dem Stichtag nicht nachgewiesen.
`MODERATE`	The recorded analysis did not resolve whether post-cutoff deforestation or forest degradation occurred; verification remains needed.	Die aufgezeichnete Analyse konnte nicht klären, ob nach dem Stichtag Entwaldung oder Walddegradation stattgefunden hat; eine Überprüfung bleibt erforderlich.
`HIGH`	The recorded analysis identified evidence requiring this plot to be treated as high geospatial risk; this does not by itself determine EUDR non-compliance.	Die aufgezeichnete Analyse hat Belege ermittelt, wegen derer diese Parzelle als Parzelle mit hohem georäumlichem Risiko zu behandeln ist; daraus allein ergibt sich keine EUDR-Nichtkonformität.
`INVALID`	The recorded analysis could not produce a valid geospatial assessment because the recorded plot or data-quality checks failed.	Die aufgezeichnete Analyse konnte keine gültige georäumliche Bewertung erstellen, weil die Prüfungen der aufgezeichneten Parzelle oder der Datenqualität fehlgeschlagen sind.

Das Ergebnis ist eine georäumliche Risikobewertung, keine eigenständige Feststellung der EUDR-Konformität.

Die bisherige Kennzahl deforestationRiskResult ist 0 niedrig (steht auch bei exempt), 1 hoch, 2 mittel oder null ohne Ergebnis (pending, skipped, failed einschließlich INVALID); während einer erneuten Analyse oder nach einer fehlgeschlagenen erneuten Analyse kann sie noch den vorherigen Wert enthalten. Maßgeblich für die Auswertung sind analysisStatus und analysis.

Parzellenbericht (PDF)

GET /api/v1/plots/{id}/report liefert den Parzellenbericht als PDF-Anhang. Er ist Englisch und enthält dieselben Nachweiszeilen wie analysis.evidence. Der Dateiname ist plot-report-<name>.pdf; jedes Zeichen außer Buchstaben, Ziffern, _ und - wird zu _ (plot-report-plot.pdf ohne Namen).

Jeder Aufruf erzeugt den Bericht neu. Laden Sie ihn einmal herunter, sobald das Ergebnis vorliegt — fragen Sie den Status über GET /api/v1/plots/{id} ab, nicht über den Bericht.

Fehlercodes

Abgelehnte Anfragen legen nichts an. Der Body enthält error und, bei den Fällen unten, einen maschinenlesbaren code:

{
  "error": "Plot geometry has too many parts: 312 (maximum 250)",
  "code": "plot_geometry_too_many_members",
  "limit": 250,
  "actual": 312
}

`code`	Status	Wann
`plot_geometry_missing`	`400`	`geojson` fehlt oder ist kein Objekt
`plot_geometry_type_unsupported`	`400`	`FeatureCollection` oder ein anderer Typ als `Polygon`, `MultiPolygon`, `Point`, `MultiPoint`; `geometryType` nennt den gesendeten Typ
`plot_commodity_group_invalid`	`400`	`commodityGroup` ist kein zulässiger Wert; die Meldung nennt die zulässigen Werte
`plot_commodity_group_required`	`400`	Weder `commodityGroup` noch `supplierArticleIds`
`plot_geometry_too_many_members`	`400`	Mehr als 250 Teile (Polygone eines `MultiPolygon`, Punkte eines `MultiPoint`)
`plot_geometry_bbox_spread_too_wide`	`400`	Bounding Box breiter als 1,0° je Achse; `actual: -1` heißt, die Geometrie ließ sich nicht vermessen
`plot_geometry_area_too_large`	`400`	Gesamtfläche über 100.000 ha
`plot_coordinates_out_of_range`	`400`	Eine Koordinate außerhalb von Längengrad ±180 / Breitengrad ±90 oder keine Zahl
`plot_supplier_article_ids_invalid`	`400`	Ein Eintrag in `supplierArticleIds` ist keine UUID, oder mehr als 5.000 IDs
`plot_species_incomplete`	`400`	Eine Holzart ohne gebräuchlichen oder wissenschaftlichen Namen, mehr als 500 Holzarten oder ein Name über 200 Zeichen
`plot_species_required`	`400`	`wood` ohne Holzart mit wissenschaftlichem Namen
`plot_geometry_too_many_vertices`	`400`	Mehr als 20.000 Punkte, gezählt wie gesendet
`plot_geometry_invalid`	`400`	Die Geometrie besteht die Prüfungen nicht, z.B. ein Ring mit weniger als drei verschiedenen Punkten
`plot_geometry_self_intersection_unrepairable`	`400`	Selbstüberschneidung, die sich nicht reparieren lässt oder deren Reparatur die Fläche um mehr als 2 % ändern würde
`plot_precision_too_low`	`400`	3 oder weniger Nachkommastellen; `precisionDigits` nennt die Anzahl

plot_geometry_too_many_members, plot_geometry_bbox_spread_too_wide und plot_geometry_area_too_large enthalten limit und actual in derselben Einheit (Teile, Grad, Hektar); teilen Sie in mehrere Parzellen auf. Bei plot_geometry_too_many_vertices vereinfachen Sie die Geometrie. Ohne code antworten: 400, wenn der Body kein JSON ist; 400, wenn ein Point oder MultiPoint über der Flächengrenze für seine size liegt (siehe Geometrie); 400, wenn size keine endliche Zahl ≥ 0 ist; 403, wenn ein Lieferantenartikel nicht zu Ihrem Unternehmen gehört.

Rezept: von GeoJSON zum Bericht

Parzelle anlegen

curl -X POST "https://app.polygon-one.com/api/v1/plots" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LIEF-4711-P03",
    "country": "BR",
    "commodityGroup": "wood",
    "size": 3.1,
    "species": [{ "commonName": "Eucalyptus", "scientificName": "Eucalyptus grandis" }],
    "productionDateFrom": "2026-01-01",
    "productionDateTo": "2026-06-30",
    "geojson": {
      "type": "Polygon",
      "coordinates": [[[-47.060123, -21.180245], [-47.058531, -21.180245], [-47.058531, -21.181934],
                       [-47.060123, -21.181934], [-47.060123, -21.180245]]]
    }
  }'

Die Antwort ist 201 mit der Parzelle unter created und warnings (hier leer). Übernehmen Sie created.id; bei einer Wiederholung enthält die Antwort "deduplicated": true.

Bis zum Ende der Analyse abfragen, dann Ergebnis lesen

Alle 15 bis 30 Sekunden, bis analysisStatus nicht mehr pending oder in_progress ist; das Ergebnis steht dann in analysis:

curl "https://app.polygon-one.com/api/v1/plots/5b0c…?fields=analysisStatus,analysis" \
  -H "Authorization: Bearer eudr_8f7d2a..."

Bericht herunterladen

curl "https://app.polygon-one.com/api/v1/plots/5b0c…/report" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -o LIEF-4711-P03.pdf

API-Dokumentation

Artikel

Lieferanten

Parzellen

Bestellungen

Import-Jobs

DDS-Erklärungen

PPWR – Verpackungsdaten

PPWR – Mengen & Mengenmeldung

Übersicht

Berechtigungen

Parzelle anlegen

Geometrie

Qualitätsprüfungen

Idempotenz

Geometrie prüfen, ohne eine Parzelle anzulegen

Status abfragen

Ergebnis lesen

Risikostufen

Parzellenbericht (PDF)

Fehlercodes

Rezept: von GeoJSON zum Bericht

​Übersicht

​Berechtigungen

​Parzelle anlegen

​Geometrie

​Qualitätsprüfungen

​Idempotenz

​Geometrie prüfen, ohne eine Parzelle anzulegen

​Status abfragen

​Ergebnis lesen

​Risikostufen

​Parzellenbericht (PDF)

​Fehlercodes

​Rezept: von GeoJSON zum Bericht

Übersicht

Berechtigungen

Parzelle anlegen

Geometrie

Qualitätsprüfungen

Idempotenz

Geometrie prüfen, ohne eine Parzelle anzulegen

Status abfragen

Ergebnis lesen

Risikostufen

Parzellenbericht (PDF)

Fehlercodes

Rezept: von GeoJSON zum Bericht