channel3-sdk


Namechannel3-sdk JSON
Version 0.1.12 PyPI version JSON
download
home_pagehttps://github.com/channel3/sdk-python
SummaryThe official Python SDK for Channel3 AI Shopping API
upload_time2025-07-09 17:51:20
maintainerNone
docs_urlNone
authorChannel3
requires_python<4.0,>=3.8
licenseMIT
keywords ai shopping ecommerce search api
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.89352s