3 Get Discovery Results
โถStep 3: Get Discovery Results
Fetch the discovered candidates once the task is completed. Each is a
source_location with the fields you need to rank and filter before
deciding what to ingest, plus collection-level meta describing the sweep.
โถWhat this step does
It returns the candidate first-mile locations discovery found, richest signal first. Each candidate carries three things that matter for the next decision:
- How precisely it's pinned:
location_precision(map-pin precision, not a confidence that the site is there):EXACT(a street address) andLOCALITY(a town centroid) resolve to a point (withlatitude/longitude);DISTRICT/REGION/BASINresolve to a polygon (withlatitude/longitudenull);UNRESOLVEDhas no geometry. - How much to trust it โ
confidence_level(high/medium/low, derived from the 0โ1match_confidence), withconfidence_reasoningand anevidence_summaryexplaining why. - What backs it โ
documented,linkage_type(deterministicwhen a verified source or dataset record states the link,inferredwhen it was reasoned from the evidence instead,probabilisticwhen it comes from the sourcing region),tie_basis(what ties the node to the company;region_onlymeans only the commodity and the region do),corroboration_count, andsources(grounding citations). - What the imagery shows โ for an
EXACT/LOCALITYpoint, the satellite check addsimagery_confidence_score,imagery_confidence_comment,supply_chain_roleandanchor_offset_m. These fields are absent when the check did not return for the node, and null when it ran but gave no value.
The meta block summarises the run: the commodities / countries actually
used (and whether they were *_inferred), a precision_breakdown, and a
best-effort completeness estimate of how much of the real first mile the sweep
likely covered.
โถWhy it's needed
Discovery is probabilistic โ it surfaces candidates, not confirmed suppliers.
This is where you apply judgement before anything touches your real data. A good
rule of thumb: only ingest high / medium-confidence candidates pinned to
a street address (EXACT). A LOCALITY point is a town centroid, so the
satellite check at it looks at a town, not a site: ask the supplier for the
street address, or pass the name to POST /discovery/validate, before
ingesting it. The default ingest gate in Step 5 leaves LOCALITY out.
Confidence says whether the site is likely real; precision only says how
sharply it was pinned. source has
already geocoded and scored these candidates, so there's no need to re-run
validate on them. Treat low-confidence candidates as leads to drop or
investigate. For a region-only hit (BASIN / REGION, no precise point) that
carries a supplier_name, you can optionally pass that name to
POST /discovery/validate (Path B) to try to pin a precise point. The
after-response script keeps the high/medium-confidence, EXACT
candidates in {{ingest_candidates}} (JSON) for Step 5's file, and the first
one in {{discovered_name}} / {{discovered_lat}} / {{discovered_lon}}.
โถVisualization
This step renders two interactive views instead of raw JSON:
- Candidates table โ every candidate ranked, with confidence and precision badges, match score, evidence, and source counts. High/medium-confidence rows pinned to a street address are tagged ingest: the ones Step 5 carries forward.
- Candidate map โ a Leaflet map with points and regions coloured by confidence (green/amber/red) and a sidebar grouped by precision; click a candidate to zoom to it and read its evidence popup.
โถResponse (200)
A JSON:API collection: data is an array of source_location resources (no
id โ they're computed, not persisted), and meta carries the run summary. See
the Examples tab for the full shape.
Other statuses: 409 while the task is still running (keep polling Step 2),
404 for an unknown / cross-org task.
โถNext Step
โ Step 5: Ingest Discovered Locations โ the trusted candidates here are already geocoded points, so they go straight to ingestion. (Only detour to Step 4: Validate a Supplier to pin a region-only candidate that lacks a precise point.)