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 with 400.

Headers

  • x-api-key โ€” required.
  • Accept: application/json

Response

  • 200 โ€” a geocode_result resource with the confidence tier resolved.
  • 400 โ€” taskId is 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.

FieldTypeDescription
typestringAlways geocode_result.
idstringThe task id.
attributes.namestringResolved facility name.
attributes.latitudenumberGeocoded latitude (WGS84).
attributes.longitudenumberGeocoded longitude (WGS84).
attributes.countrystring | nullNormalized country name.
attributes.country_codestring | nullNormalized country code.
attributes.citystring | nullNormalized city.
attributes.admin1string | nullFirst-level admin area (state / region).
attributes.geocoding_precisionstring | nullHow 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" | nullConfidence 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_commentstring | nullHuman-readable rationale behind confidence_level.
attributes.commodity_typestring | nullCommodity type applied to the geocode; null when none was sent.
attributes.company_identifierstringThe request's company_identifier; absent when none was sent.
attributes.imagery_confidence_scorenumber | nullSatellite-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_commentstring | nullOne-sentence explanation of imagery_confidence_score. Absent and null as for the score.
attributes.supply_chain_rolestring | nullfirst_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_typestring | nullNode kind (mill, port, collection_centre, โ€ฆ). Absent when validation has not returned.
attributes.node_categorystring | nullCanonical category of node_type: primary_processing | secondary_processing | aggregation | plot | logistics | commercial.
attributes.intake_materialstring | nullWhat the site takes in: raw_harvest | processed_intermediate | unknown.

Required scope: geocode:read