Channel3 Python SDK
The official Python SDK for the Channel3 API — a universal product database powering AI shopping apps and agents.
Documentation
Full API documentation and guides are available at channel3.docs.buildwithfern.com.
Runtime Compatibilities
| Requirement | Version |
|---|---|
| Python | >= 3.10 |
| HTTP client | httpx >= 0.21.2 |
| Async backend | aiohttp >= 3.13.4 (optional extra) |
| Pydantic | >= 1.9.2 (v1 and v2 supported) |
| OS | Linux, macOS, Windows |
| Typing | Fully typed — py.typed marker included |
Installation
pip install channel3-sdk
# or
poetry add channel3-sdk
For async support with aiohttp:
pip install "channel3-sdk[aiohttp]"
Authentication
The SDK authenticates via an x-api-key header. Pass your key when initializing the client:
from channel3 import Channel3Client
client = Channel3Client(api_key="YOUR_API_KEY")
Async client
from channel3 import AsyncChannel3Client
client = AsyncChannel3Client(api_key="YOUR_API_KEY")
Usage
Search products
response = client.products.search(query="organic cotton t-shirt", limit=10)
for product in response.products:
print(product.title, product.offers[0].price if product.offers else None)
Paginate through results
Search responses include a next_page_token for cursor-based pagination:
page_token = None
while True:
response = client.products.search(query="sneakers", page_token=page_token)
for product in response.products:
print(product.title)
page_token = response.next_page_token
if not page_token:
break
Visual search by image
response = client.products.image_search(
image_url="https://example.com/photo.jpg",
)
Find similar products
response = client.products.similar(product_id="prod-12345")
Look up a product by URL
product = client.products.lookup(url="https://example.com/product/abc")
Browse brands and categories
Cursor-paginated listing:
brands = client.brands.list(limit=50)
print(brands.items) # list[Brand]
print(brands.next_cursor) # pass as `cursor` for the next page
categories = client.categories.list(page_size=50)
Track prices
# Start tracking
client.price_tracking.start(canonical_product_id="prod-12345")
# Get price history
history = client.price_tracking.get_history("prod-12345")
# List active subscriptions
subs = client.price_tracking.list_subscriptions()
# Stop tracking
client.price_tracking.stop(canonical_product_id="prod-12345")
Type Intellisense
All types are importable from the top-level channel3 package:
from channel3 import Channel3Client, SearchResponse, Product, Brand
# Full autocomplete in your IDE
response: SearchResponse = client.products.search(query="headphones")
product: Product = response.products[0]
Resource clients are accessible via dot notation — type client. in your editor to discover:
| Accessor | Methods |
|---|---|
client.products |
search, image_search, similar, lookup, retrieve, enrich |
client.brands |
list, search, get |
client.categories |
list, search |
client.price_tracking |
start, stop, get_history, list_subscriptions |
client.websites |
list |
Error Handling
The SDK raises typed exceptions per HTTP status code:
from channel3.errors import UnauthorizedError, PaymentRequiredError, BadRequestError
try:
client.products.search(query="test")
except UnauthorizedError:
print("Invalid API key")
except PaymentRequiredError:
print("Upgrade your plan")
except BadRequestError as e:
print(e.body) # parsed error response
Advanced
Retries
Automatic exponential backoff on 5xx and network errors (default: 2 retries):
response = client.products.search(
query="shoes",
request_options={"max_retries": 5},
)
Timeouts
Default timeout is 60 seconds. Override per-client or per-request:
client = Channel3Client(api_key="YOUR_API_KEY", timeout=30.0)
# Per-request
response = client.products.search(
query="shoes",
request_options={"timeout_in_seconds": 10},
)
Raw Response Access
Access HTTP headers and status alongside parsed data:
response = client.products.with_raw_response.search(query="shoes")
print(response.status_code)
print(response.headers)
print(response.data) # parsed SearchResponse
Custom HTTP Client
Pass your own httpx client for proxies, custom certs, or connection pooling:
import httpx
from channel3 import Channel3Client
client = Channel3Client(
api_key="YOUR_API_KEY",
httpx_client=httpx.Client(proxy="http://proxy:8080"),
)
Reference
See the full API reference in reference.md.
Contributing
See CONTRIBUTING.md for development setup and guidelines.
1 maintainer
Metadata
1 maintainer
Release files for channel3-sdk 4.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| channel3_sdk-4.0.0.tar.gz | 83.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| channel3_sdk-4.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 237.0 kB
Release files / channel3_sdk-4.0.0.tar.gz
| Download URL | channel3_sdk-4.0.0.tar.gz |
|---|---|
| Size | 83.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
17779995aaa1d4d6f4c9d8f4e6021991f1e612db6e8a6749782465bd7a90b829
|
|
BLAKE2b-256 checksum How to use checksums |
636efb8e42ebae8f974ac08bdaa3883d7f37b26cfc44dc959eda6cd40a159b84
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / channel3_sdk-4.0.0-py3-none-any.whl
| Download URL | channel3_sdk-4.0.0-py3-none-any.whl |
|---|---|
| Size | 153.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
21a63d94629747928e2064c3a4a01aecf1ca9aff75340a32e1402cae2873be95
|
|
BLAKE2b-256 checksum How to use checksums |
84d3523e1795a00b5127c44a846d93248d30040fe73c21d6ac7324ac142d9cf2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency log
