First-Mile Discovery Workflow

The front door to the FM API: start from nothing more than a company or supplier name and end with confirmed supply-chain locations ingested and ready for deforestation / EUDR analysis.

Discovery answers the question the rest of the platform assumes you've already solved — where is this company's first mile? It wraps a grounded LLM + geocoding + imagery pipeline that reads public evidence, proposes candidate supply/operating locations, and scores each one so you can decide which are safe to trust.

Discovery has two independent entry points — they are counterparts, not sequential steps. Pick the one that matches what you're starting from:

  • POST /discovery/source — you have a company and want to map its first mile. Returns many candidate locations, each already geocoded and scored with a confidence tier and evidence.
  • POST /discovery/validate — you already know a specific supplier by name and want its single most-likely facility point plus a confidence tier.

Both converge on the same destination: keep the points you trust and hand them to ingestion. Discovery is probabilistic — it surfaces candidates with confidence and evidence — so you review before promoting anything into your real supply-chain data.

Every step renders an interactive visualization — status panels, a ranked candidate table, confidence-coloured Leaflet maps, and an ingest-file preview — rather than just the raw API response, so you can review as you go.

The two paths

Path A — you have a COMPANY                 Path B — you have a SUPPLIER
───────────────────────────                ───────────────────────────
1. POST /discovery/source                   POST /discovery/validate
2. GET  .../source/{id}/status  (poll)         → one facility:
3. GET  .../source/{id}/results                  point + confidence_level
   → many candidates, each already             (name [+ address] you have)
     geocoded + confidence-scored
                 │                                        │
                 └───────────────────┬────────────────────┘
                                     ▼
                  keep the high / medium-confidence
                  locations that resolved to a point
                                     ▼
   POST /ingestions/assets  → ingest as facilities / plots
                                     ▼
   continue with Facility / Supplier Ingestion,
   then Deforestation / EUDR Compliance (link across)

source and validate are alternatives, not a sequence — source already returns each candidate as a geocoded, confidence-scored point, so you do not re-run validate on them. The one time you'd combine them: a source candidate that resolved only to a region (no precise point) but carries a supplier name — pass that name to validate to try to pin a precise point. Ingestion is the key bridge: it turns whichever points you trust into supply-chain locations.

Use cases

  • Supply-chain mapping from a name — you have a customer's supplier list (just company names) and need to locate their upstream facilities
  • EUDR onboarding — discover candidate plots/mills for a commodity + country, keep the high-confidence ones, and ingest them for deforestation due diligence
  • Supplier confirmation — you know a specific supplier and want a single high-confidence point with a confidence tier (Path B / validate, standalone)
  • Coverage gap analysis — read the discovery meta.completeness estimate to see how much of a company's first mile the sweep is likely to have found

Endpoint map

Discovery has two entry points (Path A and Path B). Both hand off into ingestion. Pick the path that matches your input, then ingest.

StepMethodPathThreads to next
A1POST/discovery/source (company, optional commodity / country)discovery task id
A2GET/discovery/source/:id/status (poll until terminal)—
A3GET/discovery/source/:id/resultscandidate locations (already geocoded)
B1POST/discovery/validate (a known supplier by name + optional address)one point + confidence_level
5POST/ingestions/assets (the points you trust, as facilities or plots)hands off to ingestion + EUDR
  • Path A (A1 → A2 → A3) maps a company's first mile — many candidates, each geocoded, scored, and evidence-backed.
  • Path B (B1) resolves a known supplier to a single point through a task you poll (or a served result at once). Also usable to pin a region-only Path A candidate — pass its supplier name here.
  • Step 5 assembles the high/medium-confidence points from either path into a location file and ingests them. It hands off to Facility / Supplier Ingestion and the EUDR workflows.

Prerequisites

  • Valid API key in the x-api-key header with geocode:read (Steps 1–4), discovery:write for the POST /discovery/source dispatch, which starts a paid sweep, and ingestions:write / ingestions:read (Step 5)
  • Familiarity with the Ingestion workflows, which Step 5 hands off into