# Channel3 Python SDK
The official Python SDK for the [Channel3](https://trychannel3.com) AI Shopping API.
## Installation
```bash
pip install channel3-sdk
```
## Quick Start
### Synchronous Client
```python
import os
from channel3_sdk import Channel3Client
# Initialize the client
client = Channel3Client(api_key="your_api_key_here")
# Or use environment variable: CHANNEL3_API_KEY
# Search for products
products = client.search(query="blue denim jacket")
for product in products:
print(f"Product: {product.title}")
print(f"Brand: {product.brand_name}")
print(f"Price: {product.price.currency} {product.price.price}")
print(f"Availability: {product.availability}")
print("---")
# Get detailed product information
product_detail = client.get_product("prod_123456")
print(f"Detailed info for: {product_detail.title}")
print(f"Brand: {product_detail.brand_name}")
if product_detail.key_features:
print(f"Key features: {product_detail.key_features}")
# Get all brands
brands = client.get_brands()
for brand in brands:
print(f"Brand: {brand.name}")
if brand.description:
print(f"Description: {brand.description}")
# Get specific brand details
brand = client.get_brand("brand_123")
print(f"Brand: {brand.name}")
```
### Asynchronous Client
```python
import asyncio
from channel3_sdk import AsyncChannel3Client
async def main():
# Initialize the async client
client = AsyncChannel3Client(api_key="your_api_key_here")
# Search for products
products = await client.search(query="running shoes")
for product in products:
print(f"Product: {product.title}")
print(f"Score: {product.score}")
print(f"Price: {product.price.currency} {product.price.price}")
# Get detailed product information
if products:
product_detail = await client.get_product(products[0].id)
print(f"Availability: {product_detail.availability}")
# Get brands
brands = await client.get_brands()
print(f"Found {len(brands)} brands")
# Run the async function
asyncio.run(main())
```
## Advanced Usage
### Visual Search
```python
# Search by image URL
products = client.search(image_url="https://example.com/image.jpg")
# Search by base64 image
with open("image.jpg", "rb") as f:
import base64
base64_image = base64.b64encode(f.read()).decode()
products = client.search(base64_image=base64_image)
```
### Multimodal Search
```python
# Combine text and image search
products = client.search(
query="blue denim jacket",
image_url="https://example.com/jacket.jpg"
)
```
### Search with Filters
```python
from channel3_sdk import SearchFilters, AvailabilityStatus
# Create search filters
filters = SearchFilters(
brand_ids=["brand_123", "brand_456"],
gender="male",
availability=[AvailabilityStatus.IN_STOCK],
price={"min_price": 50.0, "max_price": 200.0}
)
# Search with filters
products = client.search(
query="jacket",
filters=filters,
limit=10
)
```
### Brand Management
```python
# Get all brands with pagination
brands = client.get_brands(page=1, size=50)
# Search for specific brands
nike_brands = client.get_brands(query="nike")
# Get detailed brand information
brand_detail = client.get_brand("brand_123")
print(f"Brand: {brand_detail.name}")
print(f"Logo: {brand_detail.logo_url}")
```
## API Reference
### Client Classes
#### `Channel3Client`
Synchronous client for the Channel3 API.
**Methods:**
- `search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` → `List[Product]`
- `get_product(product_id)` → `ProductDetail`
- `get_brands(query=None, page=1, size=100)` → `List[Brand]`
- `get_brand(brand_id)` → `Brand`
#### `AsyncChannel3Client`
Asynchronous client for the Channel3 API.
**Methods:**
- `async search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` → `List[Product]`
- `async get_product(product_id)` → `ProductDetail`
- `async get_brands(query=None, page=1, size=100)` → `List[Brand]`
- `async get_brand(brand_id)` → `Brand`
### Models
#### `Product`
- `id: str` - Unique product identifier
- `score: float` - Search relevance score
- `title: str` - Product title
- `description: Optional[str]` - Product description
- `brand_name: str` - Brand name
- `image_url: str` - Main product image URL
- `price: Price` - Price information
- `availability: AvailabilityStatus` - Availability status
- `variants: List[Variant]` - Product variants
#### `ProductDetail`
- `title: str` - Product title
- `description: Optional[str]` - Product description
- `brand_id: Optional[str]` - Brand identifier
- `brand_name: Optional[str]` - Brand name
- `image_urls: Optional[List[str]]` - Product image URLs
- `price: Price` - Price information
- `availability: AvailabilityStatus` - Availability status
- `key_features: Optional[List[str]]` - Key product features
- `variants: List[Variant]` - Product variants
#### `Brand`
- `id: str` - Unique brand identifier
- `name: str` - Brand name
- `logo_url: Optional[str]` - Brand logo URL
- `description: Optional[str]` - Brand description
#### `Variant`
- `product_id: str` - Associated product identifier
- `title: str` - Variant title
- `image_url: str` - Variant image URL
#### `SearchFilters`
- `brand_ids: Optional[List[str]]` - Brand ID filters
- `gender: Optional[Literal["male", "female", "unisex"]]` - Gender filter
- `price: Optional[SearchFilterPrice]` - Price range filter
- `availability: Optional[List[AvailabilityStatus]]` - Availability filters
#### `SearchFilterPrice`
- `min_price: Optional[float]` - Minimum price
- `max_price: Optional[float]` - Maximum price
#### `Price`
- `price: float` - Current price
- `compare_at_price: Optional[float]` - Original price (if discounted)
- `currency: str` - Currency code
#### `AvailabilityStatus`
Enum with values: `IN_STOCK`, `OUT_OF_STOCK`, `PRE_ORDER`, `LIMITED_AVAILABILITY`, `BACK_ORDER`, `DISCONTINUED`, `SOLD_OUT`, `UNKNOWN`
## Error Handling
The SDK provides specific exception types for different error conditions:
```python
from channel3_sdk import (
Channel3AuthenticationError,
Channel3ValidationError,
Channel3NotFoundError,
Channel3ServerError,
Channel3ConnectionError
)
try:
products = client.search(query="shoes")
except Channel3AuthenticationError:
print("Invalid API key")
except Channel3ValidationError as e:
print(f"Invalid request: {e.message}")
except Channel3NotFoundError:
print("Resource not found")
except Channel3ServerError:
print("Server error - please try again later")
except Channel3ConnectionError:
print("Connection error - check your internet connection")
```
## Environment Variables
- `CHANNEL3_API_KEY` - Your Channel3 API key
## Requirements
- Python 3.8+
- requests
- aiohttp
- pydantic
## License
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/channel3/sdk-python",
"name": "channel3-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "ai, shopping, ecommerce, search, api",
"author": "Channel3",
"author_email": "alex@trychannel3.com",
"download_url": "https://files.pythonhosted.org/packages/d5/c3/12ba8442ba8d9fb9c0b152bfad580d40f3d575f4a1650bd005855d79cc09/channel3_sdk-0.1.12.tar.gz",
"platform": null,
"description": "# Channel3 Python SDK\n\nThe official Python SDK for the [Channel3](https://trychannel3.com) AI Shopping API.\n\n## Installation\n\n```bash\npip install channel3-sdk\n```\n\n## Quick Start\n\n### Synchronous Client\n\n```python\nimport os\nfrom channel3_sdk import Channel3Client\n\n# Initialize the client\nclient = Channel3Client(api_key=\"your_api_key_here\")\n# Or use environment variable: CHANNEL3_API_KEY\n\n# Search for products\nproducts = client.search(query=\"blue denim jacket\")\n\nfor product in products:\n print(f\"Product: {product.title}\")\n print(f\"Brand: {product.brand_name}\")\n print(f\"Price: {product.price.currency} {product.price.price}\")\n print(f\"Availability: {product.availability}\")\n print(\"---\")\n\n# Get detailed product information\nproduct_detail = client.get_product(\"prod_123456\")\nprint(f\"Detailed info for: {product_detail.title}\")\nprint(f\"Brand: {product_detail.brand_name}\")\nif product_detail.key_features:\n print(f\"Key features: {product_detail.key_features}\")\n\n# Get all brands\nbrands = client.get_brands()\nfor brand in brands:\n print(f\"Brand: {brand.name}\")\n if brand.description:\n print(f\"Description: {brand.description}\")\n\n# Get specific brand details\nbrand = client.get_brand(\"brand_123\")\nprint(f\"Brand: {brand.name}\")\n```\n\n### Asynchronous Client\n\n```python\nimport asyncio\nfrom channel3_sdk import AsyncChannel3Client\n\nasync def main():\n # Initialize the async client\n client = AsyncChannel3Client(api_key=\"your_api_key_here\")\n \n # Search for products\n products = await client.search(query=\"running shoes\")\n \n for product in products:\n print(f\"Product: {product.title}\")\n print(f\"Score: {product.score}\")\n print(f\"Price: {product.price.currency} {product.price.price}\")\n \n # Get detailed product information\n if products:\n product_detail = await client.get_product(products[0].id)\n print(f\"Availability: {product_detail.availability}\")\n \n # Get brands\n brands = await client.get_brands()\n print(f\"Found {len(brands)} brands\")\n\n# Run the async function\nasyncio.run(main())\n```\n\n## Advanced Usage\n\n### Visual Search\n\n```python\n# Search by image URL\nproducts = client.search(image_url=\"https://example.com/image.jpg\")\n\n# Search by base64 image\nwith open(\"image.jpg\", \"rb\") as f:\n import base64\n base64_image = base64.b64encode(f.read()).decode()\n products = client.search(base64_image=base64_image)\n```\n\n### Multimodal Search\n\n```python\n# Combine text and image search\nproducts = client.search(\n query=\"blue denim jacket\",\n image_url=\"https://example.com/jacket.jpg\"\n)\n```\n\n### Search with Filters\n\n```python\nfrom channel3_sdk import SearchFilters, AvailabilityStatus\n\n# Create search filters\nfilters = SearchFilters(\n brand_ids=[\"brand_123\", \"brand_456\"],\n gender=\"male\",\n availability=[AvailabilityStatus.IN_STOCK],\n price={\"min_price\": 50.0, \"max_price\": 200.0}\n)\n\n# Search with filters\nproducts = client.search(\n query=\"jacket\",\n filters=filters,\n limit=10\n)\n```\n\n### Brand Management\n\n```python\n# Get all brands with pagination\nbrands = client.get_brands(page=1, size=50)\n\n# Search for specific brands\nnike_brands = client.get_brands(query=\"nike\")\n\n# Get detailed brand information\nbrand_detail = client.get_brand(\"brand_123\")\nprint(f\"Brand: {brand_detail.name}\")\nprint(f\"Logo: {brand_detail.logo_url}\")\n```\n\n## API Reference\n\n### Client Classes\n\n#### `Channel3Client`\nSynchronous client for the Channel3 API.\n\n**Methods:**\n- `search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` \u2192 `List[Product]`\n- `get_product(product_id)` \u2192 `ProductDetail`\n- `get_brands(query=None, page=1, size=100)` \u2192 `List[Brand]`\n- `get_brand(brand_id)` \u2192 `Brand`\n\n#### `AsyncChannel3Client` \nAsynchronous client for the Channel3 API.\n\n**Methods:**\n- `async search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` \u2192 `List[Product]`\n- `async get_product(product_id)` \u2192 `ProductDetail`\n- `async get_brands(query=None, page=1, size=100)` \u2192 `List[Brand]`\n- `async get_brand(brand_id)` \u2192 `Brand`\n\n### Models\n\n#### `Product`\n- `id: str` - Unique product identifier\n- `score: float` - Search relevance score\n- `title: str` - Product title\n- `description: Optional[str]` - Product description\n- `brand_name: str` - Brand name\n- `image_url: str` - Main product image URL\n- `price: Price` - Price information\n- `availability: AvailabilityStatus` - Availability status\n- `variants: List[Variant]` - Product variants\n\n#### `ProductDetail`\n- `title: str` - Product title\n- `description: Optional[str]` - Product description\n- `brand_id: Optional[str]` - Brand identifier\n- `brand_name: Optional[str]` - Brand name\n- `image_urls: Optional[List[str]]` - Product image URLs\n- `price: Price` - Price information\n- `availability: AvailabilityStatus` - Availability status\n- `key_features: Optional[List[str]]` - Key product features\n- `variants: List[Variant]` - Product variants\n\n#### `Brand`\n- `id: str` - Unique brand identifier\n- `name: str` - Brand name\n- `logo_url: Optional[str]` - Brand logo URL\n- `description: Optional[str]` - Brand description\n\n#### `Variant`\n- `product_id: str` - Associated product identifier\n- `title: str` - Variant title\n- `image_url: str` - Variant image URL\n\n#### `SearchFilters`\n- `brand_ids: Optional[List[str]]` - Brand ID filters\n- `gender: Optional[Literal[\"male\", \"female\", \"unisex\"]]` - Gender filter\n- `price: Optional[SearchFilterPrice]` - Price range filter\n- `availability: Optional[List[AvailabilityStatus]]` - Availability filters\n\n#### `SearchFilterPrice`\n- `min_price: Optional[float]` - Minimum price\n- `max_price: Optional[float]` - Maximum price\n\n#### `Price`\n- `price: float` - Current price\n- `compare_at_price: Optional[float]` - Original price (if discounted)\n- `currency: str` - Currency code\n\n#### `AvailabilityStatus`\nEnum with values: `IN_STOCK`, `OUT_OF_STOCK`, `PRE_ORDER`, `LIMITED_AVAILABILITY`, `BACK_ORDER`, `DISCONTINUED`, `SOLD_OUT`, `UNKNOWN`\n\n## Error Handling\n\nThe SDK provides specific exception types for different error conditions:\n\n```python\nfrom channel3_sdk import (\n Channel3AuthenticationError,\n Channel3ValidationError,\n Channel3NotFoundError,\n Channel3ServerError,\n Channel3ConnectionError\n)\n\ntry:\n products = client.search(query=\"shoes\")\nexcept Channel3AuthenticationError:\n print(\"Invalid API key\")\nexcept Channel3ValidationError as e:\n print(f\"Invalid request: {e.message}\")\nexcept Channel3NotFoundError:\n print(\"Resource not found\")\nexcept Channel3ServerError:\n print(\"Server error - please try again later\")\nexcept Channel3ConnectionError:\n print(\"Connection error - check your internet connection\")\n```\n\n## Environment Variables\n\n- `CHANNEL3_API_KEY` - Your Channel3 API key\n\n## Requirements\n\n- Python 3.8+\n- requests\n- aiohttp\n- pydantic\n\n## License\n\nMIT License\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The official Python SDK for Channel3 AI Shopping API",
"version": "0.1.12",
"project_urls": {
"Homepage": "https://github.com/channel3/sdk-python",
"Repository": "https://github.com/channel3/sdk-python"
},
"split_keywords": [
"ai",
" shopping",
" ecommerce",
" search",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "67ea1a3a310aae8ae0a3417877606069bfc28c80ba43e4fab64baf32c5beaa25",
"md5": "dbf7efb5f9e9a6070386aa9da449b19b",
"sha256": "e0732ec7066fe097efee678ff9475f28e089eb5082732854650f984ff99c6fd8"
},
"downloads": -1,
"filename": "channel3_sdk-0.1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dbf7efb5f9e9a6070386aa9da449b19b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 8314,
"upload_time": "2025-07-09T17:51:19",
"upload_time_iso_8601": "2025-07-09T17:51:19.570321Z",
"url": "https://files.pythonhosted.org/packages/67/ea/1a3a310aae8ae0a3417877606069bfc28c80ba43e4fab64baf32c5beaa25/channel3_sdk-0.1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d5c312ba8442ba8d9fb9c0b152bfad580d40f3d575f4a1650bd005855d79cc09",
"md5": "805d2c2846b1b411cd38172b92b8d842",
"sha256": "b67d27988c20b7823e4e2089a9c5a5b56311c9b824711403245e08c60520fc1a"
},
"downloads": -1,
"filename": "channel3_sdk-0.1.12.tar.gz",
"has_sig": false,
"md5_digest": "805d2c2846b1b411cd38172b92b8d842",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 8522,
"upload_time": "2025-07-09T17:51:20",
"upload_time_iso_8601": "2025-07-09T17:51:20.678554Z",
"url": "https://files.pythonhosted.org/packages/d5/c3/12ba8442ba8d9fb9c0b152bfad580d40f3d575f4a1650bd005855d79cc09/channel3_sdk-0.1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 17:51:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "channel3",
"github_project": "sdk-python",
"github_not_found": true,
"lcname": "channel3-sdk"
}
JSON
