File Profiling

POST /ingestions/profile?limit=25
Accept: application/geo+json
Content-Type: multipart/form-data

file=@supplier-plots.geojson

Accepts CSV, TSV, Excel, JSON, GeoJSON, GeoPackage and zipped Shapefile, up to 100 MB. An unrecognised file type is a 415.

A GeoJSON FeatureCollection with a non-standard top-level properties member. A spec-compliant FeatureCollection has no such member, but that block carries the file-level aggregates and is the point of the endpoint.

{
  "type": "FeatureCollection",
  "properties": {
    /* file-level aggregates — always complete */
  },
  "features": [
    /* per-row detail — best first, capped by `limit` */
  ],
}

The two halves answer different questions. properties describes the file and is never truncated, whatever limit you pass. features is the per-row detail and is capped, ordered most-precise-first.

Every row is classified on its own evidence. A mixed file is the common case, and reporting one verdict for the whole upload is how a customer misreads their own data.

checks_possible is not a compliance statement. It lists what can be measured on that geometry — before any measurement has run. A row with forest_loss in the list has not been checked for forest loss; it is merely capable of being checked.

The ranking is by measurable footprint — how precisely the row locates a thing on the ground, which is what decides the measurements it can carry. It is a capability ordering, not a quality grade: a mill at rank 4 is not a defective plot, it is a different kind of thing supporting different work. For cattle, a facility point is the required geolocation rather than a substitute.

What each one means:

• plot_boundary — a polygon under the catchment band. The strongest thing a file can carry: measurements are taken on the boundary you supplied.
• point_with_area — a point that states its own size. Measured on a square derived from the declared area.
• point_no_area — a bare point with no area resolved and nothing indicating a facility. measured_on is none because the file supplies no footprint and inventing a square the customer never gave us would make the read untrue.
• facility — an aggregation or processing site. Measured on a catchment around the point, and it supports a genuinely different set of checks rather than a reduced one. A facility that supplied its own boundary is measured on that boundary rather than on a catchment inferred from a point.
• sourcing_area — a polygon at or above 100 ha. A catchment rather than a plot.
• address_only — place text but no coordinates. Nothing can be measured until it is geocoded.
• point_large_area — only under the EUDR lens. A point declaring an area at or above the band (4 ha by default), where the regulation requires a polygon. Without the lens there is no band, and a point that states its size is simply point_with_area whatever the number.
• unusable — no footprint and no address.

So the core read sees seven kinds; the EUDR lens sees eight.

field_coverage reports which of the 14 EUDR Due Diligence Statement fields your file carries, and in which column. Keyed by the DDS statement field names, so you can line the report up against what you will eventually have to send.

Three states, not two:

• found — the column is named.
• absent — we looked, and your file has none.
• undetermined — we could not look, or nothing detects this field yet.

The third state matters. A detector returning nothing otherwise conflates "we looked and your file has no producer column" with "we could not look". The first is a fact about your data, the second about our service, and reporting the second as the first is a lie.

Every entry also carries required — whether every DDS needs it. That is our own list, not a reading of the regulation, and it separates the core fields from the rest. Filing a DDS can ask for more, such as the operator's EORI and phone. Nine of the sixteen fields are required:

operator_name, operator_address, operator_email, operator_country, product_type, product_quantity, hs_code, production_country, supplier_name.

Two of those — operator_name and operator_address — are required and undetectable from a location file (a location file does not describe the operator placing goods on the EU market). operator_email and operator_country likewise. They report undetermined with reason: no_detector and required: true, so you can see up front that you will be asked for them.

plot_area is resolved on its own pathway rather than by the schema detector, and it reports that pathway's outcome. Where the area column was never looked for — no point rows to measure, or the detector unavailable — it reports undetermined carrying the same area_detection value, not absent, which would claim a polygon file states no area when nobody asked.

Schema detection only runs for CSV, XLS and XLSX. A GeoJSON, GeoPackage or shapefile upload therefore reports every field as undetermined — nothing was looked at, and saying absent would claim otherwise. species_common_name, species_scientific_name, operator_name and operator_address are always undetermined (reason: no_detector), listed so the report says "we did not look" rather than omitting them, which would read as absent.

The profiler and validation read each row's commodity from one column and report what they found:

"commodity_column_report": {
  "column": "Crop",
  "distinct_values": ["cocoa", "coffee"],
  "invalid": [{ "value": "hemp", "rows": 1 }],
  "blank_rows": 1
}

POST /ingestions/profile returns the block before you upload, so you can fix an unsupported value at the source. Validation returns the same block for the same file.

Which column is used. The first of these that applies:

1. The column you name with commodity_column. The name is matched ignoring case and surrounding spaces. For a shapefile, give the truncated DBF name.
2. A column named exactly commodity_type.
3. The column the profiler scores as the most likely commodity column. This step is skipped when you declare commodity_type.

commodity_column_report.column tells you which column was used. If you name a column the file does not have, POST /ingestions/profile returns 422 COMMODITY_COLUMN_NOT_FOUND listing the file's columns, and an upload with that column fails its task with the same message.

Each row is checked against its own commodity. A coffee row is checked against coffee's commodity layer, catchment, travel time, legality, natural hazard and land-use-change context, even in a file that is mostly cocoa. The commodity a row is stored with, its supplier unit, its record and its DDS commodity are the same value.

What a declared commodity_type does. It never overrides a cell. It is the file's commodity:

Without a declaration, the file's commodity is the most common value in the column, and it plays the same role.

Unsupported values are flagged per row. Such a row carries commodity_invalid: true, which reads back as assessments.core.flags.commodity_invalid on GET /ingestions/assets/:taskId?include=assessments. A blank cell is counted in blank_rows and is not flagged. The flag and the report appear whenever a column is used, whether or not you declare commodity_type.

geography reports the countries the rows fall in. It is usually the fastest way to notice a region you did not expect in a file you did not create.

"geography": {
  "state": "found",
  "countries": [
    {"country": "Ghana", "rows": 62},
    {"country": "Cote d'Ivoire", "rows": 9}
  ],
  "rows_unresolved": 0,
  "rows_unplaced": 3
}

Derived from geometry, not from a country column. Of four real cocoa files only one names its country, so reading the column would answer for a quarter of uploads. Countries are ordered by row count, largest first.

Three outcomes, kept apart because they mean different things:

state is undetermined when the lookup did not run. That is a fact about us rather than about your file, and it is reported as such rather than as an empty country list, which would claim the file lands nowhere. rows_unplaced still counts, since it describes your geometry rather than the lookup.

supplier_clusters answers the question a plot file rarely answers itself: how many supplier units does this describe? It groups parcels by geography, commodity and country. field_coverage and supplier_names separately report which columns name the producers.

Supplier names do not change this count. supplier_names supplies editable labels for the computed units. To preserve a reviewed partition, return the confirmed supplier_unit IDs; see the uploaded-unit rules below.

"supplier_clusters": {
  "basis": "geometry_clusters",
  "partition": "travel_time",
  "window_minutes": 120,
  "split_by": ["commodity", "country"],
  "supplier_count": 2,
  "site_supplier_count": 0,
  "cluster_supplier_count": 2,
  "address_supplier_count": 0,
  "cut_km": 50.0,
  "rows_unplaced": 1,
  "rows_ungrouped": 0,
  "clusters": [
    {"unit": "8f2c1a04e7b3", "plot_count": 178, "centroid": [-74.6977, -11.2533],
     "extent_km": 73.0, "bounds": [-75.1, -11.6, -74.2, -10.9],
     "commodity": "cocoa", "country": "Peru", "travel_unit": 1},
    {"unit": "b91d40c6aa17", "plot_count": 17, "centroid": [-73.6979, -11.2798],
     "extent_km": 2.6, "bounds": [-73.71, -11.29, -73.69, -11.27],
     "commodity": "coffee", "country": "Peru", "travel_unit": 1}
  ]
}

supplier_clusters counts and labels the units. supplier_units is what you need to put one on a screen and send it to ingestion: the rows it holds, what the file says about it, and which of those facts still need a person.

"supplier_units": {
  "basis": "travel_time",
  "window_minutes": 120,
  "split_by": ["commodity", "country"],
  "unit_count": 2,
  "rows_unassigned": 0,
  "refinement": {"status": "ready", "window_minutes": 120,
                 "resolution_m": 500, "algorithm": "tt1"},
  "units": [
    {
      "unit": "8f2c1a04e7b3",
      "kind": "parcels",
      "plot_count": 178,
      "row_ids": [0, 1, 5],
      "commodity": "cocoa",
      "country": "Peru",
      "detected_kinds": ["plot_boundary"],
      "centroid": [-74.6977, -11.2533],
      "bounds": [-75.1, -11.6, -74.2, -10.9],
      "travel_unit": 1,
      "shed": {"type": "MultiPolygon", "coordinates": []},
      "fields": {
        "product_type": {"state": "detected", "value": "cocoa",
                         "source": "column:commodity", "reason": null, "required": true},
        "production_country": {"state": "suggested", "value": "Peru",
                               "source": "geometry", "reason": "placed_by_geometry",
                               "required": true},
        "product_quantity": {"state": "missing", "value": null, "source": null,
                             "reason": "no_column", "required": true}
      },
      "missing_required": ["product_quantity"],
      "needs_confirmation": ["production_country"],
      "plots": {"type": "FeatureCollection", "features": []}
    }
  ]
}

basis, window_minutes and split_by repeat what supplier_clusters reports, so this block reads on its own. rows_unassigned counts rows that reached no unit, for the same reasons supplier_clusters reports under rows_unplaced and rows_ungrouped.

Units are ordered parcel units first, largest first, then sites.

supplier_names reports the columns that could name the suppliers supplier_clusters counted. The two are separate on purpose: this one prefills an editable name, and never drives the count.

The reason is that a file's own labels sit at whatever grain its author had in mind. Across four real cocoa files the best candidate was an aggregator in one, a cooperative in two, and a collection village in the fourth — 1, 1, 2 and 32 values for files holding 1, 1, 2 and 1 actual suppliers. Counting on that field would have billed the last file thirty-two times over.

"supplier_names": {
  "state": "found",
  "reason": null,
  "source_column": "cooperativ",
  "candidates": [
    {"column": "cooperativ", "coalesced_from": ["cooperativ", "cooperat_1"],
     "grain": "cooperative", "distinct_values": 2, "fill_pct": 100.0,
     "id_like": false, "samples": ["COOP. HIJINI R.L.", "COOP. COVENDO R.L."]}
  ],
  "per_unit": [
    {"unit": 1, "rows": 247, "suggested_name": "COOP. HIJINI R.L.",
     "distinct_values": 2}
  ]
}

state is found when a candidate survived, absent when columns were read and none did, and undetermined when there were no columns to read — so "this file names nobody" stays distinguishable from "we could not look".

Unlike field_coverage, this reads the frame's column names directly and needs no schema detection, so it answers on GeoJSON, GeoPackage and shapefile uploads too — which is most plot files.

Pass include_eudr_profile=true to add the one regulatory distinction that cannot be derived without it: the polygon-required band. This enables the point_large_area kind and produces eudr_payload, a prefill block that ingest already knows how to consume. Override the band with area_band_ha.

eudr_payload is deliberately conservative. It carries only fields whose value cannot be silently wrong, and only when a column holds one single value across every row — a column that varies row to row describes the rows, not the consignment, and collapsing it would invent a fact.

Three fields are reported in field_coverage but never prefilled, because ingest fills only fields you left empty, so a wrong value would land exactly where nobody is positioned to notice it:

• supplier_address and supplier_name — read downstream as the operator address and name. The operator is the entity placing goods on the EU market, and it is not your supplier.
• product_quantity — ingest stamps the unit itself as kilograms, and a detected column may be tonnes, gross weight, unit count or area. A Quantity (tonnes) column would land on a statement wrong by a factor of 1000.

If you know which entity or unit a column describes, the coverage report still shows you it exists, and you can supply the value yourself.

The profile describes the uploaded data and the fields available for preparing a DDS. It runs no compliance assessment or submission validation.

Geolocation. rows_needing_a_decision counts rows carrying a decision, including identity conflicts. It is not a count of rejected or unfileable rows. The decision describes what the file leaves open:

An identity conflict may also attach a decision to a boundary or facility group. No decision means this profiler has no open question for the group; it does not mean the locations have passed assessment or DDS submission checks.

Assessment footprints. Read geometry_types and footprint alongside kind. A facility group can contain both points and supplied boundaries. measured_on reports the most common basis in a mixed group, not the basis of every row. In sourcing-area runs, supplied boundaries define the sourcing areas. In facility runs, polygons of at least 5,000 ha define sourcing areas directly; smaller boundaries use their centroids to derive travel-time catchments, as site points do. Assessments can identify plots within those areas, and those plots' results and locations can be used in a DDS. Do not turn a facility or sourcing_area classification into a blanket DDS exclusion.

For plot input supplied as points, ingestion can resolve parcel boundaries or use fallback squares. The absence of an uploaded boundary does not itself mean that no plot geometry will be produced.

Statement fields. field_coverage reports what the file supplies. Missing required values need to be supplied before submission, but profile coverage alone does not determine whether a DDS can be filed.

Unknown query parameters are rejected with a 400.

properties.plot_warnings reports warnings over the complete file, independently of the preview's limit or supplier grouping. status: complete includes the applied min_area_ha (normally 0.05), the detected plot_id_column, and rows with source_row, plot_id, codes, measured_area_ha and duplicate_of. Duplicate references name both the original source row and its plot ID; geometry_groups uses source row positions. row is the post-cleanup profile position used by the review's exclusions. Positions are zero-based parsed-file rows, not spreadsheet line numbers. In merged Excel workbooks, source_row is the position after matching worksheets have been combined and full-row duplicates removed. Warning preflight uses ingestion's header promotion and matching-sheet merge. With include_unit_plots=true, properties.review_rows carries the complete post-cleanup rows for optional exclusion, independently of supplier units. These retain original row fields: unit plots may stamp detected or suggested unit values onto their rows, so they cannot replace raw review rows for public exclusions.

below_area_floor applies to plot boundaries below the configured minimum, not points or facilities. duplicate_geometry applies to matching cleaned geometries under different nonblank plot IDs. Repeat deliveries under the same ID are not flagged as copies. These findings require no acknowledgement, never block an upload, and never remove rows automatically.

The original member of a duplicate group is included for identity lookup. It has duplicate_of: null and may have codes: [] when it is not also below the area floor; only subsequent distinct plot IDs receive duplicate_geometry.

Direct POST /ingestions/assets uploads run the same checks after the file lands and before upload-time assessments. This includes multipart and signed-URL uploads; the signed-URL creation response cannot report on bytes not yet uploaded. Inspect GET /ingestions/:id → data.attributes.plot_warnings, or request GET /ingestions/assets/:id?include=normalised_data → meta.plot_warnings. These are compact summaries with row_count, geometry_group_count, and a details_url. GeoJSON implicitly includes this summary in collection properties; NDJSON includes it in the metadata header. Follow details_url to GET /ingestions/:id/plot-warnings with Accept: application/json and the same task-read authorization to download every finding and duplicate group. The complete JSON is stored beside uploads, outside task JSONB, and streamed only on that request. No findings are truncated. Read source identities there rather than assuming a profile position equals a result-page position. List and PATCH responses do not include the summary.

The warning preflight has a 60-second upstream deadline. Validation opens a fresh source stream afterward. Warning detection or persistence failure is logged and does not stop ingestion; an absent snapshot reads as unavailable.

To correct or exclude rows before direct submission, preview with POST /ingestions/profile, edit the source file, and submit the corrected bytes. Direct submission otherwise proceeds automatically, keeping all warned rows. status: unavailable explicitly distinguishes a failed/unrecorded check from a completed check with no warnings. Older uploads are not backfilled. App users see the same findings, optional exclusions, and a retry option for unavailable checks before submission. Public screening remains free for the visitor; these warnings do not change organisation allowances, payment rules, or assessment verdicts.