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) and LOCALITY (a town centroid) resolve to a point (with latitude / longitude); DISTRICT / REGION / BASIN resolve to a polygon (with latitude / longitude null); UNRESOLVED has no geometry.
  • How much to trust it โ€” confidence_level (high / medium / low, derived from the 0โ€“1 match_confidence), with confidence_reasoning and an evidence_summary explaining why.
  • What backs it โ€” documented, linkage_type (deterministic when a verified source or dataset record states the link, inferred when it was reasoned from the evidence instead, probabilistic when it comes from the sourcing region), tie_basis (what ties the node to the company; region_only means only the commodity and the region do), corroboration_count, and sources (grounding citations).
  • What the imagery shows โ€” for an EXACT / LOCALITY point, the satellite check adds imagery_confidence_score, imagery_confidence_comment, supply_chain_role and anchor_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.)