Get Supplier Confidence Results
Fetch the finished result of a task started by POST /discovery/validate.
Call this once GET /discovery/validate/{taskId}/status reports
status: completed.
The payload is the same geocode_result shape as the served 200 from
POST /discovery/validate: the geocoded point and normalized fields with
confidence_level / confidence_comment filled in. It is self-contained, so
a caller that only kept the taskId still gets the full resource to gate and
(optionally) ingest on. Confidence is enrichment, not a gate: a task that
finished without a canonical tier returns confidence_level: null; treat
low (and null) as not safe to ingest.
โถRequest
โถMethod & Path
GET /discovery/validate/{taskId}/results
โถPath parameters
taskId(UUID, required) โ the task id. A non-UUID value is rejected with400.
โถHeaders
x-api-keyโ required.Accept: application/json
โถResponse
- 200 โ a
geocode_resultresource with the confidence tier resolved. - 400 โ
taskIdis not a valid UUID. - 401 / 403 โ missing or invalid key, or the key lacks
geocode:read. - 404 โ the task is unknown or belongs to a different organization.
- 409 โ the task is still processing; keep polling
โฆ/status. - 422 โ
GEOCODE_NO_RESULT: the geocoder found no usable location for the supplier. - 502 โ
GEOCODE_UPSTREAM_ERROR: the task failed upstream (retry the POST), or a transient failure reading the confidence check (retry this call).
โถResponse schema
Only the data payload is described; the meta / links envelope is
documented centrally.
| Field | Type | Description |
|---|---|---|
type | string | Always geocode_result. |
id | string | The task id. |
attributes.name | string | Resolved facility name. |
attributes.latitude | number | Geocoded latitude (WGS84). |
attributes.longitude | number | Geocoded longitude (WGS84). |
attributes.country | string | null | Normalized country name. |
attributes.country_code | string | null | Normalized country code. |
attributes.city | string | null | Normalized city. |
attributes.admin1 | string | null | First-level admin area (state / region). |
attributes.geocoding_precision | string | null | How sharply the address geocoded (ROOFTOP / RANGE_INTERPOLATED / GEOMETRIC_CENTER / APPROXIMATE), or for a registry-matched facility the map-pin tier (EXACT / LOCALITY / DISTRICT / REGION / BASIN / UNRESOLVED). Not a confidence that the site is there; see confidence_level. |
attributes.confidence_level | "low" | "medium" | "high" | null | Confidence tier; see the Validate folder's confidence guidance. Null when the check was unavailable, inconclusive or invalid, including failed commodity checks. Review low/null before compliance use; the overall proxy score is not returned. |
attributes.confidence_comment | string | null | Human-readable rationale behind confidence_level. |
attributes.commodity_type | string | null | Commodity type applied to the geocode; null when none was sent. |
attributes.company_identifier | string | The request's company_identifier; absent when none was sent. |
attributes.imagery_confidence_score | number | null | Satellite-imagery confidence (0..1) that the point shows the facility. Absent when the imagery check did not return; null when it ran but could not score the point. |
attributes.imagery_confidence_comment | string | null | One-sentence explanation of imagery_confidence_score. Absent and null as for the score. |
attributes.supply_chain_role | string | null | first_mile | downstream | unknown. Derived from intake material, then node type, as on source. Guides whether traversal stops or goes upstream. For ingestion, also review node classification, intake material, pin and link evidence; the role alone is not an ingestability verdict. Absent when validation has not returned. |
attributes.node_type | string | null | Node kind (mill, port, collection_centre, โฆ). Absent when validation has not returned. |
attributes.node_category | string | null | Canonical category of node_type: primary_processing | secondary_processing | aggregation | plot | logistics | commercial. |
attributes.intake_material | string | null | What the site takes in: raw_harvest | processed_intermediate | unknown. |
Required scope:
geocode:read