/pcpartpicker/products/search

POST /api/pcpartpicker/products/search

Price: 20 credits

Search one PCPartPicker component category — CPUs, coolers, motherboards, memory, storage, video cards, power supplies, cases, case fans, monitors, keyboards, mice, headphones, speakers, webcams, sound and network cards, fan controllers, thermal paste, optical drives, operating systems and UPS units. Narrows by any option filter the category publishes (manufacturer, chipset, socket, memory type, form factor, colour, rating and the rest), by numeric ranges such as price, capacity, clock speed, wattage, length and port counts, and by a keyword matched against product names. Returns each product with its PCPartPicker code, name, image, the category's own spec columns, the current cheapest price and the community star rating.

How to use it

One call covers one `category`; there is no cross-category search here, so resolve a bare product name with /pcpartpicker/products/suggestions first if you do not know which category it belongs to. `filters` and `ranges` are named with the filter-group headings this category shows, and they differ per category — read them from /pcpartpicker/products/filters rather than guessing, because an unknown group or option is rejected with the list of valid ones. Values inside one group are ORed and separate groups are ANDed. Numeric groups other than Price take a unit specific to the group — GB, MHz, W, mm, or a bare count. `region` switches merchants and currency, not the catalogue, so the same product appears in every region with a different price, which is why the Price range is read against whichever `region` was requested. Note that `price` here is PCPartPicker's cached listing figure and can disagree with the live merchant offers; the Price range filter and /pcpartpicker/products get their number from the merchant table. Each card's `specs` entry here is {name, value: str} — one value per spec name; /pcpartpicker/products carries its own, differently-shaped `specs` ({name, values: list[str]}), since some specs there are multi-valued.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• category string required — Component category to search (one of: "cpu", "cpu-cooler", "motherboard", "memory", "internal-hard-drive", "video-card", "power-supply", "case", "headphones", "keyboard", "mouse", "speakers", "webcam", "monitor", "os", "sound-card", "wired-network-card", "wireless-network-card", "case-fan", "fan-controller", "thermal-paste", "external-hard-drive", "optical-drive", "ups")
• region string — PCPartPicker country site, which decides the merchants and the currency of every price (default: "us"; one of: "au", "at", "be", "ca", "cz", "dk", "fi", "fr", "de", "hu", "ie", "it", "nl", "nz", "no", "pl", "pt", "ro", "sa", "sk", "es", "se", "uk", "us")
• search string nullable — Keyword matched against product names inside the chosen category (examples: "astral", "9800x3d"; minLength: 1)
• filters array nullable — Option filters, each naming a filter group of this category and the option labels to accept. Groups and labels are category-specific and are rejected with the list of what this category publishes
  • name string required — Filter group name exactly as the category publishes it (examples: "Manufacturer", "Memory Type", "Chipset"; minLength: 1)
  • values array required — Option labels to accept; several labels widen the group, several groups intersect (examples: ["Asus","MSI"]; minItems: 1)
• ranges array nullable — Numeric filters, each naming a numeric group of this category with a lower and/or upper bound in that group's own unit. Price is the group named Price and takes whole currency units
  • name string required — Numeric filter group name exactly as the category publishes it (examples: "Price", "Memory", "Boost Clock"; minLength: 1)
  • minimum number nullable — Lower bound in the group's own unit; omitted means the group's published minimum
  • maximum number nullable — Upper bound in the group's own unit; omitted means the group's published maximum
• sort string nullable — Ordering, given as the value or the label this category publishes; a leading minus reverses it. Rejected with the list of what this category offers (examples: "price", "-rating", "Name (Ascending)"; minLength: 1)
• count integer required — Max number of results to return (min: 1; max: 20000)

Response

• @type string (default: "PcpartpickerProductCard")
• id string required
• internal_id string nullable
• url string nullable
• name string nullable
• image string nullable
• price number nullable
• rating number nullable
• review_count integer nullable
• specs array (default: [])
  • @type string (default: "PcpartpickerSpec")
  • name string required
  • value string required

Errors

• 422 — A filter group, an option label or a sort value that this category does not publish Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — The category page did not come back with a product table Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.