Compare parts

A comparison puts parts side by side on the specifications that matter for that kind of part, with the values read from each part’s datasheet. One part is the reference. Every other part gets one verdict per specification against it, a count of the specifications that are the same or covered, and what distributors hold now. Use it to check a substitute before you qualify it, or to choose between parts you already have in mind. To find candidates first, use Find alternate parts or Search for parts.

Start a comparison

Send your own list in parts: 2 to 6 parts, compared as given. The first is the reference the others are compared with.

import os
import uuid

import requests

response = requests.post(
    "https://api.partfinder.dev/v1/compare",
    headers={
        "Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"parts": [{"mpn": "TPS54331DR"}, {"mpn": "TPS5430DDAR"}]},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/compare", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ parts: [{ mpn: "TPS54331DR" }, { mpn: "TPS5430DDAR" }] }),
});
console.log(await response.json());

curl https://api.partfinder.dev/v1/compare \
  -X POST \
  -H "Authorization: Bearer $PARTFINDER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"parts": [{"mpn": "TPS54331DR"}, {"mpn": "TPS5430DDAR"}]}'

Or send one part in mpn to compare it with its alternates, the list GET /v1/alternates returns:

import os
import uuid

import requests

response = requests.post(
    "https://api.partfinder.dev/v1/compare",
    headers={
        "Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"mpn": "TPS54331DR"},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/compare", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ mpn: "TPS54331DR" }),
});
console.log(await response.json());

curl https://api.partfinder.dev/v1/compare \
  -X POST \
  -H "Authorization: Bearer $PARTFINDER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mpn": "TPS54331DR"}'

Send mpn or parts, not both. manufacturer is only needed when several companies make a part with that number: beside mpn in the first shape, inside each part in the second ({"mpn": "NE555N", "manufacturer": "STMicroelectronics"}). The answer is 202 with the comparison’s id, a Location header pointing at it, and Retry-After: 10. Idempotency-Key is optional: send a new value for each comparison, and the same value only when retrying that same comparison after a timeout. The retry returns the comparison the first call started.

When a comparison is refused

Every part you send is checked before anything starts. A refusal names the part in its summary, and nothing is started:

400 invalid_request: neither or both of mpn and parts, parts with fewer than 2 or more than 6 parts, or a manufacturer beside parts instead of inside each part.
404 part_not_found: no distributor lists a part number you sent exactly, usually a typo or a partial number. did_you_mean carries listed part numbers that begin with what you sent, when there are any.
422 not_a_specific_part: a part you sent is a question, a category or a generic specification, not one part. When it described a class of parts, did_you_mean carries real part numbers to retry with.
503 verification_unavailable: we could not confirm a part number is real right now. Retry shortly.

Every code is on the Errors page.

Get the result

Read GET /v1/compare/{id} after the 10 seconds in Retry-After. While status is still processing, the answer’s summary and Retry-After give the wait before the next read, 9 seconds:

import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/compare/f2d22c25-e694-428b-bbb8-3948e60d3c7b",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
print(response.json())

const response = await fetch("https://api.partfinder.dev/v1/compare/f2d22c25-e694-428b-bbb8-3948e60d3c7b", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());

curl https://api.partfinder.dev/v1/compare/f2d22c25-e694-428b-bbb8-3948e60d3c7b \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"

status ends as complete, with the parts, or failed, when the comparison could not be completed: submit it again. Every poll counts toward your rate limit. To be told instead of polling, register a webhook: compare.completed names the comparison when it ends.

What comes back

{
  "as_of": "2026-10-12T02:49:29.479Z",
  "summary": "TPS54331DR compared with 1 part. TPS5430DDAR: Same or covers on 1 of 4 specs both datasheets state.",
  "notice": "Informational only. ...",
  "id": "f2d22c25-e694-428b-bbb8-3948e60d3c7b",
  "status": "complete",
  "created_at": "2026-10-12T02:48:51.204Z",
  "completed_at": "2026-10-12T02:49:29.479Z",
  "columns": ["Input Voltage Range", "Output Voltage", "Output Current", "Package Type"],
  "parts": [
    {
      "mpn": "TPS54331DR",
      "manufacturer": "Texas Instruments",
      "reference": true,
      "match": null,
      "lifecycle": "Active",
      "specs": {
        "Input Voltage Range": "3.5 V to 28 V",
        "Output Voltage": "Adjustable down to 0.8 V",
        "Output Current": "3 A continuous",
        "Package Type": "SOIC-8"
      },
      "datasheet_url": "https://www.ti.com/lit/gpn/tps54331",
      "supply": {
        "stock": { "value": 1148628, "unit": "units" },
        "distributor_count": 22,
        "lead_time_median": { "value": 84, "unit": "days" }
      },
      "comparison": null
    },
    {
      "mpn": "TPS5430DDAR",
      "manufacturer": "Texas Instruments",
      "reference": false,
      "match": null,
      "lifecycle": "Active",
      "specs": {
        "Input Voltage Range": "5.5 V to 36 V",
        "Output Voltage": "adjustable down to 1.22 V",
        "Output Current": "3 A continuous",
        "Package Type": "SO PowerPAD DDA 8-pin"
      },
      "datasheet_url": "https://www.ti.com/lit/ds/symlink/tps5430.pdf",
      "supply": {
        "stock": { "value": 1192476, "unit": "units" },
        "distributor_count": 22,
        "lead_time_median": { "value": 140, "unit": "days" }
      },
      "comparison": {
        "verdicts": {
          "Input Voltage Range": "narrower",
          "Output Voltage": "narrower",
          "Output Current": "same",
          "Package Type": "different"
        },
        "stated": 4,
        "same_or_covers": 1,
        "summary": "Same or covers on 1 of 4 specs both datasheets state."
      }
    }
  ]
}

summary is one sentence you can relay as it is. When no part to compare with was found, it says so and parts holds the reference alone.
columns are the specifications chosen for this kind of part. Every part’s specs has one entry per column: the value its datasheet states, or null when it states none. datasheet_url is the datasheet the values were read from.
parts lists the reference first (reference: true, comparison: null), then each part compared with it. For an alternate of the part you sent in mpn, match is the parts catalogue’s classification, as on alternates; it is null for the reference and for your own list.
supply is what distributors hold now, in the same shape as alternates.
comparison holds one verdict per column, stated (the specifications both datasheets state), same_or_covers (how many of those are same or covers) and a one-sentence summary.

What each verdict means

Verdict	Meaning
`same`	The same value, however written.
`covers`	Its range contains the reference’s value or range.
`narrower`	Its range does not contain the reference’s whole range.
`higher` / `lower`	A single value above or below; whether that is better depends on the specification.
`different`	The two cannot be put on one scale.
`not_stated`	One of the datasheets states none.

A verdict compares what the datasheets state; it is not a qualification. Confirm fit against the datasheets before you buy or substitute.

List and delete

GET /v1/compare lists your comparisons, newest first, one page at a time, the same way as BOMs. DELETE /v1/compare/{id} removes a comparison and its results. With a key you created for one of your customers (Serving your own customers), a customer sees only its own comparisons.

Get Started

Core Concepts

Guides

Integrations

Start a comparison

When a comparison is refused

Get the result

What comes back

What each verdict means

List and delete

​Start a comparison

​When a comparison is refused

​Get the result

​What comes back

​What each verdict means

​List and delete

Start a comparison

When a comparison is refused

Get the result

What comes back

What each verdict means

List and delete