Research a part

One call returns everything we know about a part. This page covers what comes back, what to do when a part number is wrong, and how caching affects what you see.

The call

import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/parts",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
    params={"mpn": "STM32F103RBT6", "country": "SG"},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/parts?mpn=STM32F103RBT6&country=SG", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());

curl "https://api.partfinder.dev/v1/parts?mpn=STM32F103RBT6&country=SG" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"

mpn is the only required parameter. country is optional: see Buying near you.

The first request for a part can take tens of seconds; later ones answer quickly. Set your client timeout to 90 seconds.

What comes back

{
  "as_of": "2026-09-24T16:01:19.747Z",
  "summary": "STM32F103RBT6 carries a supply-chain risk score of 32 out of 100 (medium). Flagged: manufacturing geography (medium), lead-time volatility (critical). 350,010 units are held across 28 distributors.",
  "notes": [],
  "part": {
    "mpn": "STM32F103RBT6",
    "manufacturer": "STMicroelectronics",
    "category": "32-bit ARM Cortex-M3 MCU",
    "lifecycle": "Active",
    "manufacturing_country": "Malaysia",
    "manufacturing_country_code": "MY"
  },
  "risk": {
    "composite": {
      "value": 32,
      "scale": 100,
      "direction": "higher_is_worse",
      "interpretation": "Medium. Combined from manufacturing geography, lead-time volatility, live disruption exposure and how hard this part is to replace."
    },
    "tier": "medium",
    "drivers": {
      "geography": {
        "tier": "medium",
        "interpretation": "Medium. Reflects the risk profile of Malaysia."
      },
      "lead_time_volatility": {
        "tier": "critical",
        "interpretation": "Critical. Lead times for this part are highly unstable."
      },
      "disruption_exposure": {
        "tier": "low",
        "interpretation": "Low. Little exposure to active disruptions. 2 active events are listed in `disruption_events`."
      },
      "replacement_difficulty": {
        "tier": "low",
        "interpretation": "Low. Easy to source from several places."
      }
    }
  },
  "supply": {
    "stock": {
      "value": 350010,
      "unit": "units"
    },
    "lead_time_median": {
      "value": 364,
      "unit": "days"
    },
    "lead_time_min": {
      "value": 52,
      "unit": "days"
    },
    "lead_time_max": {
      "value": 364,
      "unit": "days"
    },
    "distributor_count": 28,
    "distributors": [
      {
        "name": "Win Source",
        "country": "United Kingdom",
        "country_code": "GB",
        "regions": [
          "Europe"
        ],
        "subregion": "Northern Europe",
        "stock": {
          "value": 91714,
          "unit": "units"
        }
      }
    ],
    "nearby": {
      "country": "Singapore",
      "country_code": "SG",
      "region": "Asia",
      "summary": "2 distributors elsewhere in Asia hold 5,765 units.",
      "distributors": [
        {
          "name": "Antrex",
          "country": "China",
          "country_code": "CN",
          "regions": [
            "Asia"
          ],
          "subregion": "Eastern Asia",
          "stock": {
            "value": 3046,
            "unit": "units"
          },
          "proximity": "same_region"
        }
      ]
    }
  },
  "datasheet": {
    "url": "https://apexcomponent.com/wp-content/uploads/2026/05/STM32F103RBT6-STMicroelectronics-Datasheet.pdf",
    "source": "other"
  },
  "alternates": [
    {
      "mpn": "XMC4100F64F128BAXQMA1",
      "manufacturer": "Infineon Technologies",
      "description": "IC MCU 32BIT 128KB FLASH 64TQFP",
      "match": "similar",
      "lifecycle": "Active",
      "supply": {
        "stock": { "value": 0, "unit": "units" },
        "distributor_count": 0,
        "lead_time_median": { "value": 91, "unit": "days" }
      }
    }
  ]
}

Trimmed for length: notice, risk.why_at_risk, risk.drivers_detail, disruption_events and recommended_actions are omitted, and distributors, nearby.distributors and alternates are cut to their first entry. Every field is listed in the reference.

Reading it without parsing it

summary is one sentence covering the score, the drivers flagged medium or above and the stock position, taken from the same supply figures returned in this response. If you are relaying to a person or a model, that line is enough on its own.

The risk score

risk.composite combines the four drivers under risk.drivers, and risk.tier is the band it falls in: low, medium, high or critical.

Driver	What it measures
`geography`	Exposure carried by where the part is made
`lead_time_volatility`	How unstable the lead times quoted for it are
`disruption_exposure`	Exposure to the events and shipping conditions in `disruption_events`
`replacement_difficulty`	How hard it would be to switch to something else

Each is a band (tier: low, medium, high or critical) and an interpretation, one sentence about this part, not a generic description of the driver. Drivers carry no number; the composite does. tier is null when there is no data for a driver, and the sentence says why.

A part in a BOM can score differently: see BOM analysis.

Disruption events

disruption_events lists the reported events and shipping conditions that most affect disruption_exposure, strongest first: ordered by effect on this part’s score, not by severity. severity is how serious the event or slowdown is in itself, not its effect on this part. Each item has a kind:

`kind`	What it is
`news`	A reported disruption, with its `id`, `root_cause`, `country`, `published_date` and a source `url` (`null` when no source article could be confirmed). Open it in full with `GET /v1/events/{id}`
`port_activity`	Ship traffic at the ports of a country this part is made in or sold from is well under its usual level, e.g. `"Ports in Mexico: ship arrivals 21% below the usual level for this time of year"`; `country` names it
`sea_route`	The same for a sea passage this part’s trade uses, e.g. `"Panama Canal: ship transits 21% below the usual level for this time of year"`

For port_activity and sea_route, id and url are null, and published_date is the last day of the week the figure covers. The list is empty when nothing affects the score noticeably.

Supply

stock and the lead times can be more recent than as_of. distributor_count is the number of distributors holding stock of this part. distributors lists those holding the most, largest first, and is not exhaustive. lead_time_min and lead_time_max are the 25th and 75th percentiles of the quoted lead times: the middle half of quotes. They come back null with a reason when that middle half is a single figure: there is no range to report.

Buying near you

Send the buyer’s country as a two-letter ISO 3166-1 code, country=SG, and supply.nearby lists the distributors holding stock in that country first, then elsewhere in its region, with a summary sentence you can relay as it is:

{
  "country": "Singapore",
  "country_code": "SG",
  "region": "Asia",
  "summary": "2 distributors elsewhere in Asia hold 5,765 units.",
  "distributors": [
    {
      "name": "Antrex",
      "country": "China",
      "country_code": "CN",
      "regions": [
        "Asia"
      ],
      "subregion": "Eastern Asia",
      "stock": {
        "value": 3046,
        "unit": "units"
      },
      "proximity": "same_region"
    },
    {
      "name": "Lankamic",
      "country": "China",
      "country_code": "CN",
      "regions": [
        "Asia"
      ],
      "subregion": "Eastern Asia",
      "stock": {
        "value": 2719,
        "unit": "units"
      },
      "proximity": "same_region"
    }
  ]
}

Each distributor in nearby.distributors carries proximity: same_country or same_region. Every distributor, here and in supply.distributors, also carries regions and subregion, the parts of the world its listing serves, following the UN geographic regions: a storefront that states a wider area than one country, such as Europe, Middle East and Africa, lists each region it covers, and subregion is null when no country is known. These are not the region values of the events feed; to find events affecting a distributor, filter events by its country_code. The nearby list is empty, and the sentence says so, when nobody near the buyer holds stock. The risk score and every other field are the same with or without country; without it, nearby is null. A value that is not a country code answers 400.

Alternates

alternates lists up to five parts that could replace this one: the same list, in the same shape, as Find alternate parts. Each carries how a supplier catalogue classifies it (match), its lifecycle and what distributors hold now. The same part in another package or ordering variant is never an alternate, the list is not ranked, and it can be empty. Confirm fit against the datasheets before substituting.

Datasheet

datasheet.url links to this part number’s datasheet: a PDF where one is published, otherwise a page carrying it. It may be hosted by a distributor rather than the manufacturer. null when no datasheet was found.

When the part number is not right

Three refusals, and none of them returns a report.

The input is not a specific part: `422`

{
  "error": "not_a_specific_part",
  "summary": "\"3A buck converter 28V\" describes a class of parts rather than one specific part. Try one of these real part numbers instead: NB682, AP3503F, AP3003.",
  "did_you_mean": ["NB682", "AP3503F", "AP3003"]
}

No supplier lists that part number: `404`

{
  "error": "part_not_found",
  "summary": "\"TPS5433\" was not found at any supplier — it looks like a partial part number. Did you mean TPS54331, TPS54332, TPS54331D?",
  "did_you_mean": ["TPS54331", "TPS54332", "TPS54331D"]
}

did_you_mean carries real part numbers on both refusals: parts of the kind you described on a 422, and the listed part numbers your input is a prefix of on a 404. TPS5433 is not an orderable part; TPS54331 and TPS54332 are.

We could not check: `503`

{
  "error": "verification_unavailable",
  "summary": "We could not confirm that \"6305-2RS\" is a real part number right now, so no report was produced. This is temporary — retry shortly."
}

Retry with backoff. This is not the same as the part not existing: that answer is 404. Here the part could not be checked.

Parts several manufacturers make

Some part numbers are made by more than one company. NE555N is listed by STMicroelectronics, Philips, Signetics and others.

import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/parts",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
    params={"mpn": "NE555N", "manufacturer": "STMicroelectronics"},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/parts?mpn=NE555N&manufacturer=STMicroelectronics", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());

curl "https://api.partfinder.dev/v1/parts?mpn=NE555N&manufacturer=STMicroelectronics" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"

Supplying it gives you a different report, not a filtered view of the same one: each manufacturer’s part is assessed on its own supply position, and lead-time volatility follows from that. Manufacturing origin follows the manufacturer too, when where that manufacturer makes the part is known; otherwise it is the part number’s origin. A manufacturer that does not list the part returns a report with no supply data rather than an error, and its lead-time volatility is correspondingly less certain. The response then carries a note saying so, with the makers that do list it:

"notes": [
  {
    "kind": "manufacturer_not_listed",
    "summary": "Texas Instruments isn't among the makers distributors list for NE555N. It's listed from STMicroelectronics, onsemi, Philips Semiconductors and others.",
    "suggestions": ["STMicroelectronics", "onsemi", "Philips Semiconductors"]
  }
]

notes is always present and empty when there is nothing to note.

Freshness

as_of is when the report was produced, up to 48 hours before your call. Read as_of rather than assuming the report was produced for your call. Supply figures are at most 24 hours old. Responses carry Cache-Control: no-store; what that means and what you may store is in Freshness.

Conventions

How scores, units and nulls work across every response.

Errors

Every status code and what to do about it.

Get Started

Core Concepts

Guides

Integrations

The call

What comes back

Reading it without parsing it

The risk score

Disruption events

Supply

Buying near you

Alternates

Datasheet

When the part number is not right

The input is not a specific part: `422`

No supplier lists that part number: `404`

We could not check: `503`

Parts several manufacturers make

Freshness

Conventions

Errors

​The call

​What comes back

​Reading it without parsing it

​The risk score

​Disruption events

​Supply

​Buying near you

​Alternates

​Datasheet

​When the part number is not right

​The input is not a specific part: 422

​No supplier lists that part number: 404

​We could not check: 503

​Parts several manufacturers make

​Freshness

Conventions

Errors

The call

What comes back

Reading it without parsing it

The risk score

Disruption events

Supply

Buying near you

Alternates

Datasheet

When the part number is not right

The input is not a specific part: `422`

No supplier lists that part number: `404`

We could not check: `503`

Parts several manufacturers make

Freshness