Discovery

Resolve supplier names and addresses to geographic locations, and discover a company's first-mile supply base โ€” all without ingesting any assets. The discovery suite is the front door of the "resolve a supplier" flow: turn a name (and optional address) into a usable latitude/longitude, or trace a company back to the production areas and intermediary nodes that supply into it, before any supply-shed, metrics, or compliance work.

Two flows

The suite splits into two sub-groups:

GroupEndpointsWhat it does
ValidatePOST /discovery/validate (+ async poll pair)Resolve a supplier you already know to a single best-match facility, via a task, or immediately on an exact-cache hit.
SourcePOST /discovery/source (+ poll pair)Discover the supply base of a company you don't yet have suppliers for โ€” potentially dozens of candidates โ€” asynchronously (dispatch โ†’ poll status โ†’ fetch results).

Facilities and plot boundaries

Discovery resolves facility locations and supply-chain leads. It does not supply verified plot boundaries. A plantation node is not a supplier's plot polygon. Some source candidates have no usable coordinates; do not turn a missing or approximate pin into a plot.

Upload a located facility as location_type: "facility". Obtain plot boundaries from the supplier or the appropriate ingestion flow.

Start with validate

  1. Validate suppliers whose names you already know. Include their address and country to distinguish companies with the same name.
  2. Use source when you need a company's suppliers, or when validation has not resolved a credible facility. Review the link evidence, pin status and imagery before carrying a candidate forward.
  3. For assessed EUDR work, upload the facilities you keep on the EUDR upload fast path.

Trace allowance

Each accepted POST /discovery/source call is one Trace, whatever its depth: a one-tier or direct-operated search, a traversal, or a continuation. An organization gets 10 Traces, and 30 once it has paid for a checkout. Epoch can grant more, and some organizations are unlimited. A parent organization and its child organizations share one allowance. Cached, failed and unspent runs do not count once settled. POST /discovery/validate spends no Traces.

Read the Traces left on GET /rate-limits/allowances. With none left, POST /discovery/source returns 402 USAGE_LIMIT_REACHED, unless a repeat without refresh or continue_from finds an existing cached result.

Rate limits

These caps apply whatever the allowance. Defaults apply per organization; an organization can have its own limits.

RequestDefault limitCache behavior
Validate300 requests/hourAn exact-cache hit returns 200 without spending the limit.
Standard one-tier source60 dispatches/hourCharged at dispatch, even when the result comes from cache.
Direct-operated sourceSeparate 120 dispatches/hour poolCharged at dispatch, even when the result comes from cache.
Traversal80 sweeps/day (the daily trace-sweep limit)Full max_sweeps charged at dispatch; unused sweeps refunded when settled.

A 429 response carries Retry-After, and data.details names the limit, the counts and resets_at. Reduce a max_sweeps that exceeds the whole daily limit. GET /rate-limits reports each limit before it is hit.

See the Validate and Source sub-folders for the endpoint pages.

Required scope: geocode:read. Dispatching a source discovery and recording a decision on it also need discovery:write.