Search cached products using query words and, when recognized, their product category. Category matching can include titles that omit the category word; insufficient category evidence falls back to title matching. An explicit category filter replaces automatic category selection. Cache-only: no live marketplace fetch.
Read result first: not_searched omits products and has_more; miss returns products: []; hit returns ranked products. An offset beyond the result set also returns miss. Check filters.applied and filters.ignored to see which inputs were used.
Exact hits carry match: all_terms. If nothing matches every word of a multi-word search, match: partial marks the closest matches, with matched_terms, dropped_terms and message; the product type stays required and filters never relax. A filter-emptied miss carries emptied_by and retry_url. Words beyond twelve appear in ignored_terms.
Filters apply before selecting a bounded result pool. A filtered request can return products absent from an unfiltered response. Results are ranked again for each request and may change between pages; offset pagination is not a snapshot. No catalogue-wide total is available.
Use compact or fields to reduce returned product fields without changing matching or ordering. Available now: Australia (prices in AUD); other marketplaces are in progress. Use currency with price bounds when you need prices in one currency. Prices are never converted; an unserved currency returns miss with emptied_by, available_regions and retry_url. dedupe keeps the first result for each provider and normalized title, so variants with identical titles can be combined.
View input schema
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "Search words. Matching uses recognized product categories and title words, with a title-match fallback. Without a searchable term the response is not_searched, even if filters are supplied.",
"default": ""
},
"limit": {
"description": "Maximum products per page. Values are clamped to the range 1–50. The response echoes the applied page_size. A non-integer value returns 422.",
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"pattern": "^-?[0-9]+$"
}
],
"default": 24
},
"min_price": {
"description": "Minimum price in each listing's stored currency. Available now: Australia (prices in AUD). Accepts 1500 or $1,500.00. Supply currency to restrict prices to one currency. Invalid values are ignored.",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"default": ""
},
"max_price": {
"description": "Maximum price, parsed like min_price. Available now: Australia (prices in AUD). Supply currency to restrict prices to one currency. A minimum above the maximum yields no matches.",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"default": ""
},
"condition": {
"type": "string",
"description": "One of new, refurbished or used. Products with no recorded condition do not match. Invalid values are ignored.",
"default": ""
},
"marketplace": {
"type": "string",
"description": "Marketplace: ebay, amazon, aliexpress, jbhifi or shein. Stored locale labels such as EBAY_AU are accepted. Takes precedence over provider.",
"default": ""
},
"provider": {
"type": "string",
"description": "Alias for marketplace. Ignored when marketplace is also supplied.",
"default": ""
},
"brand": {
"type": "string",
"description": "Exact brand, case-insensitive. Products with no stored brand do not match.",
"default": ""
},
"fresher_than": {
"type": "string",
"description": "Only products checked since this relative age (7d, 24h, 30m) or ISO-8601 date/time. Times without a timezone use UTC. Invalid values are ignored.",
"default": ""
},
"sort": {
"type": "string",
"description": "best_match (default), price (cheapest first) or price_desc (most expensive first). Invalid values use best_match and are listed in filters.ignored.",
"default": ""
},
"offset": {
"description": "Number of ranked products to skip. Negative values use zero; invalid values use zero and appear in filters.ignored. Results may change between requests.",
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"pattern": "^-?[0-9]+$"
}
]
},
"compact": {
"description": "Set true for title, price, currency, condition, permalink and id only. False or empty returns full products. Invalid values are ignored. The applied selection appears in fields.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
}
],
"default": ""
},
"fields": {
"type": "string",
"description": "Comma-separated product fields, e.g. title,price,url. Overrides compact; id and permalink are always included. Unknown names are dropped. If none are valid, the full projection is returned and fields appears in filters.ignored.",
"default": ""
},
"category": {
"description": "Published browse slug (mobile-phones) or numeric eBay category ID (9355), not a display name. Replaces automatic category selection. filters.applied echoes the supplied category and resolved ID.",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"default": ""
},
"currency": {
"type": "string",
"description": "ISO-4217 currency code. Available now: Australia (prices in AUD); other marketplaces are in progress. Filters to prices stored in that currency and never converts prices. A currency that is not served returns miss with emptied_by, available_regions and retry_url. Use with min_price and max_price.",
"default": ""
},
"dedupe": {
"description": "Set true to keep the first result for each provider and normalized title, using the selected sort order. Off by default. Variants with identical titles may be combined. deduped counts removed rows in the ranked pool before paging.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
}
],
"default": ""
}
},
"required": [],
"additionalProperties": false
}