Validate
Resolve a supplier you already know to its single best-match facility
location (latitude/longitude) plus a confidence tier — no supply-shed
generation, no persisted record. Use it as the first step of a "resolve a
supplier" flow before any downstream metrics or compliance work; treat low
(and null) confidence as not safe to ingest.
▶Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /discovery/validate | Resolve a supplier name (+ optional address) to its single top facility location; starts a task unless a served candidate answers at once |
| GET | /discovery/validate/{taskId}/status | Poll the task; shows the geocoded point as soon as it is known |
| GET | /discovery/validate/{taskId}/results | Fetch the finished result with its confidence tier |
▶Polling
Geocoding takes seconds and the confidence tier minutes for a cold lookup,
so both run in the background. POST /discovery/validate returns 202
with a task id at once; poll …/status (its result carries the point as
soon as it is geocoded) until completed, then read …/results. A served
candidate returns a plain 200 with its tier and nothing to poll, so handle
both 202 and 200.
▶Resolution and confidence
Send a supplier name and, where possible, an address including the country.
There is no separate country input. A name alone may match in another country.
commodity_type is optional; omit it rather than guess. Set refresh: true
to request a fresh resolution.
Results include the best-match point, confidence tier, comment and imagery score when available. Confidence supports a location match; it does not establish sourcing legality. The overall numeric score is not returned. Review low or null confidence before ingestion or compliance use.
▶When confidence is null
A point can have null confidence while enrichment is pending, when a check failed or could not score it, or when the pipeline returned an invalid verdict. Null is not a positive result. Check the status and comment; review low or null results before using them for compliance work.
Required scope:
geocode:read