Skip to main content
PartFinder responses are built to be used as they are. Scores explain themselves, measures include their units, unknown values are explicit rather than absent, and every response says how fresh its data is. Pass them straight to an agent, a UI or business logic.

​
Scores

Every score in a PartFinder response is a structured object, never a bare number: the scale and the direction travel with the value. A score object always contains four fields:
​
number
required
The numeric score.
​
number
required
The maximum value the score can take. 100 means the score runs from 0 to 100.
​
string
required
Which end of the scale is worse. One of higher_is_worse or higher_is_better.
​
string
required
A plain-language sentence summarizing what this score means for this specific part. It can be relayed as-is, without re-deriving it.
A complete score object looks like this:
The composite risk score is explained by four drivers: A driver carries no number. Each is a band and a sentence:
tier is low, medium, high or critical, or null when there is no data for the driver, in which case interpretation says why. Read it as “where to look”, not as a figure to compute with; the composite is the number.

​
Units

Every measure carries its unit inline. Stock levels, lead times, pricing, and other quantities are never bare numbers: each is an object pairing a value with its unit. Examples of measure objects:
A measure object renders correctly without anyone guessing whether 14 means days, weeks, or hours.

​
Unknown values and nulls

When a value is not known, PartFinder represents it as an explicit null with an accompanying reason field explaining the data gap. Fields are never omitted. Read reason on any null value to see why it is unknown.
Common reasons for null values include:
  • No distributor has current stock or pricing for the part
  • The part has reached end-of-life and distributor data has aged out
  • The data source for this attribute has not yet been indexed for this MPN
Every field in the schema is always present. A missing key is an error: report it.

​
Freshness and the as_of timestamp

Every successful PartFinder response includes an as_of field: an ISO 8601 UTC timestamp for the data in that response. Errors carry error and summary instead: see Errors.
as_of says when the data in the response was produced. It can be earlier than the moment you receive it. If freshness matters for your use case, such as real-time procurement decisions or active disruption monitoring, read as_of and apply your own tolerance rather than assuming every field was fetched at that instant. You may store any response you receive and reuse it for as long as you like. Its figures are as of its as_of; call again for current ones. Responses carry Cache-Control: no-store, which tells proxies and CDNs not to keep a copy. It does not limit what you store in your own systems.
Show as_of alongside anything you pass to users or downstream systems.

​
Informational-use notice

Every successful PartFinder response carries a notice field with a consistent informational-use disclaimer:
This field is always present and always contains the same text. You can display it in your UI, include it in agent outputs, or log it alongside results. It is provided as a field rather than only in API documentation, so a consumer that never read the docs still has the disclaimer in context.
Pass notice through to whoever consumes the data.