Search - Channel3

The /v1/search endpoint is the core of Channel3. Make a requests and get back a list of products with prices, availability, images, and retailer offers.

Basic search

import Channel3 from "@channel3/sdk";

const client = new Channel3(); // reads CHANNEL3_API_KEY from env

const results = await client.products.search({
  query: "merino wool sweater",
});

console.log(results.products[0].title);
console.log(results.products[0].offers[0].price);

from channel3_sdk import Channel3

client = Channel3()  # reads CHANNEL3_API_KEY from env

results = client.products.search(query="merino wool sweater")

print(results.products[0].title)
print(results.products[0].offers[0].price)

curl -X POST https://api.trychannel3.com/v1/search \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "merino wool sweater"}'

Filters

Narrow results with filters. Every filter is optional — combine as many as you need.

const results = await client.products.search({
  query: "running shoes",
  filters: {
    price: { min_price: 50, max_price: 150 },
    availability: ["InStock", "LimitedAvailability"],
    gender: "male",
    category: "running-shoes", // category slug
    brand_ids: ["brand_id_1"], // from /v1/brands/search
  },
  limit: 20,
});

results = client.products.search(
    query="running shoes",
    filters={
        "price":        {"min_price": 50, "max_price": 150},
        "availability": ["InStock", "LimitedAvailability"],
        "gender":       "male",
        "category":     "running-shoes",
        "brand_ids":    ["brand_id_1"],
    },
    limit=20,
)

Popular filters

These are the filters most integrations use. See the API reference for the complete list.

Filter	Type	Description
`price`	`{ min_price?, max_price? }`	Price range in the request’s currency.
`availability`	`string[]`	One or more of `InStock`, `LimitedAvailability`, `PreOrder`, `BackOrder`, `SoldOut`, `OutOfStock`.
`gender`	`string`	`male`, `female`, or `unisex`.
`category`	`string`	A category slug (e.g. `running-shoes`). See Categories.
`brand_ids`	`string[]`	Limit to specific brands. Resolve brand IDs via `/v1/brands/search`.
`attributes`	`Record<string, string[]>`	Filter by structured attribute key/value pairs — e.g. `{ "connectivity": ["USB"] }`. Attribute keys come from category detail. See Advanced Search.
`colors`	`{ hex: string, percentage?: number }[]`	Filter by color palette using hex values (Beta).
`age`	`string`	`newborn`, `infant`, `toddler`, `kids`, or `adult`.
`dimensions`	`{ length?, width?, height?, weight? }`	Filter by physical size and weight, each `{ min?, max?, unit }`. See Dimension Filters.

Pagination

Use next_page_token from the response to fetch the next page. You can page up to 500 products total. A request with a next_page_token costs one credit. See pricing.

const page1 = await client.products.search({ query: "running shoes" });
console.log("Page 1:", page1.products.length, "products");

if (page1.next_page_token) {
  const page2 = await client.products.search({
    query: "running shoes",
    page_token: page1.next_page_token,
  });
  console.log("Page 2:", page2.products.length, "products");
}

page1 = client.products.search(query="running shoes")
print(f"Page 1: {len(page1.products)} products")

if page1.next_page_token:
    page2 = client.products.search(
        query="running shoes",
        page_token=page1.next_page_token,
    )
    print(f"Page 2: {len(page2.products)} products")

Keyword search

Set mode: "keyword" to skip semantic (vector) search and use exact keyword matching instead. This path is optimized for low latency — use it when users type specific product names or SKUs, or when you need the fastest possible search response.

const results = await client.products.search({
  query: "Nike Air Max 90",
  config: { mode: "keyword" },
});

results = client.products.search(
    query="Nike Air Max 90",
    config={"mode": "keyword"},
)

⌘I