> ## Documentation Index
> Fetch the complete documentation index at: https://help.polygon-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geo-Analyse über die API

> Parzellengeometrie senden, die Entwaldungsanalyse abwarten, das Ergebnis als JSON lesen und den Parzellenbericht als PDF laden

## Ü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](/api-reference/introduction); wie Sie einen Schlüssel anlegen, steht unter
[Einstellungen → API-Schlüssel](/de/eudr/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.

<Info>
  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.
</Info>

## Parzelle anlegen

`POST /api/v1/plots` legt **eine** Parzelle an und startet ihre Analyse. Alle Felder stehen in der
[Endpunkt-Referenz](/api-reference/endpoint/plots/create); für eine Integration wichtig:

* `geojson` ist Pflicht (siehe [Geometrie](#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](#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:

```json theme={null}
{
  "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](/de/eudr/einstellungen#analyse-für-länder-mit-geringem-risiko-art-13)) |

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](/de/eudr/optional/plots)). 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.

```json theme={null}
{
  "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. |

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

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).

<Warning>
  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.
</Warning>

## Fehlercodes

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

```json theme={null}
{
  "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](#geometrie)); `400`, wenn `size` keine
endliche Zahl ≥ 0 ist; `403`, wenn ein Lieferantenartikel nicht zu Ihrem Unternehmen gehört.

## Rezept: von GeoJSON zum Bericht

<Steps>
  <Step title="Parzelle anlegen">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="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`:

    ```bash theme={null}
    curl "https://app.polygon-one.com/api/v1/plots/5b0c…?fields=analysisStatus,analysis" \
      -H "Authorization: Bearer eudr_8f7d2a..."
    ```
  </Step>

  <Step title="Bericht herunterladen">
    ```bash theme={null}
    curl "https://app.polygon-one.com/api/v1/plots/5b0c…/report" \
      -H "Authorization: Bearer eudr_8f7d2a..." \
      -o LIEF-4711-P03.pdf
    ```
  </Step>
</Steps>