# AdsonAI Python SDK
[](https://badge.fury.io/py/adsonai-sdk)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
Python SDK for AdsonAI - AI-powered contextual advertising platform.
## 🚀 Quick Start
### Installation
```bash
pip install adsonai-sdk
```
### Get API Key
1. Visit [AdsonAI Dashboard](https://adsonai.vercel.app/api-keys)
2. Create a new API key
3. Copy your key (starts with `adsonai_`)
### Basic Usage
```python
from adsonai_sdk import AdsonAI
# Initialize client
client = AdsonAI(api_key="your_adsonai_api_key")
# Get contextual ads
ads = client.get_contextual_ads("I need running shoes", max_ads=3)
# Display results
for ad in ads:
print(f"🏷️ {ad.brand_name} - {ad.product_name}")
print(f"💬 {ad.ad_text}")
print(f"💰 Bid: ${ad.bid_amount}")
if ad.landing_url:
print(f"🔗 {ad.landing_url}")
print()
client.close()
```
## 📖 Documentation
### AdsonAI Class
#### `AdsonAI(api_key, base_url=None, timeout=30)`
Initialize the AdsonAI client.
**Parameters:**
- `api_key` (str): Your AdsonAI API key
- `base_url` (str, optional): Custom API base URL
- `timeout` (int, optional): Request timeout in seconds
#### `test_connection()`
Test connection to the AdsonAI API.
**Returns:** `bool` - True if successful
#### `get_contextual_ads(query, max_ads=3, context=None)`
Get contextual ads using AI matching.
**Parameters:**
- `query` (str): User query or conversation context
- `max_ads` (int): Maximum ads to return (1-10)
- `context` (dict, optional): Additional context for matching
**Returns:** `List[Ad]` - List of matched ads
### Ad Object
**Properties:**
- `id`: Unique ad identifier
- `brand_name`: Brand or company name
- `product_name`: Product or service name
- `description`: Ad description
- `ad_text`: Display text for the ad
- `bid_amount`: Bid amount in USD
- `landing_url`: Landing page URL (optional)
- `target_keywords`: Target keywords
- `status`: Ad status
### Exception Handling
```python
from adsonai_sdk import AdsonAI, AuthenticationError, APIError, ValidationError
try:
client = AdsonAI(api_key="your_key")
ads = client.get_contextual_ads("search query")
except AuthenticationError:
print("Invalid API key")
except APIError as e:
print(f"API error: {e}")
except ValidationError as e:
print(f"Validation error: {e}")
```
## 💡 Examples
### Context Manager
```python
with AdsonAI(api_key="your_key") as client:
ads = client.get_contextual_ads("smart home devices")
for ad in ads:
print(f"{ad.brand_name}: {ad.ad_text}")
```
### Convenience Function
```python
from adsonai_sdk import get_ads
# Quick one-liner
ads = get_ads("your_key", "gaming laptop", max_ads=5)
```
### Chatbot Integration
```python
def get_sponsored_suggestion(user_message):
try:
ads = get_ads(API_KEY, user_message, max_ads=1)
if ads:
ad = ads[0]
return f"💡 {ad.brand_name}: {ad.ad_text}"
except Exception:
pass
return None
# In your chatbot
user_input = "I need a new coffee maker"
suggestion = get_sponsored_suggestion(user_input)
if suggestion:
print(suggestion)
```
### E-commerce Integration
```python
def show_sponsored_products(search_query):
with AdsonAI(api_key=API_KEY) as client:
ads = client.get_contextual_ads(search_query, max_ads=3)
print("🎯 Sponsored Products:")
for ad in ads:
print(f"• {ad.brand_name} - {ad.product_name}")
print(f" {ad.ad_text}")
print(f" ${ad.bid_amount} | {ad.landing_url}")
```
## 🔧 Advanced Usage
### With Additional Context
```python
context = {
'user_location': 'San Francisco',
'user_age': '25-34',
'interests': ['fitness', 'technology'],
'budget': 'mid-range'
}
ads = client.get_contextual_ads(
"workout equipment",
max_ads=5,
context=context
)
```
### Error Handling with Retries
```python
import time
from adsonai_sdk import AdsonAI, APIError
def get_ads_with_retry(query, max_retries=3):
for attempt in range(max_retries):
try:
with AdsonAI(api_key=API_KEY) as client:
return client.get_contextual_ads(query)
except APIError as e:
if e.status_code == 429: # Rate limit
time.sleep(2 ** attempt) # Exponential backoff
continue
raise
return []
```
## 🧪 Testing
```bash
# Set your API key
export ADSONAI_API_KEY="your_actual_api_key"
# Run tests
python -m pytest tests/
# Run integration test
python test_live_api.py
```
## 📝 License
MIT License - see LICENSE file for details.
## 🤝 Support
- 📚 Documentation: [https://docs.adsonai.com](https://docs.adsonai.com)
- 🎛️ Dashboard: [https://adsonai.vercel.app](https://adsonai.vercel.app)
- 🐛 Issues: [GitHub Issues](https://github.com/adsonai/python-sdk/issues)
- 📧 Email: developers@adsonai.com
## 🛣️ Roadmap
- [ ] Async support with `aiohttp`
- [ ] Batch ad matching
- [ ] Advanced analytics
- [ ] Webhook support
- [ ] Ad performance tracking
Raw data
{
"_id": null,
"home_page": "https://github.com/adsonai/adsonai-python-sdk",
"name": "adsonai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "advertising, ai, llm, contextual, ads, monetization",
"author": "AdsonAI Team",
"author_email": "AdsonAI Team <support@adsonai.com>",
"download_url": "https://files.pythonhosted.org/packages/a5/f6/59695b2854bb4b9df913bb81334c4b82ff69ff498d951cc929e4cbcb2f41/adsonai-1.0.0.tar.gz",
"platform": null,
"description": "# AdsonAI Python SDK\n\n[](https://badge.fury.io/py/adsonai-sdk)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nPython SDK for AdsonAI - AI-powered contextual advertising platform.\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install adsonai-sdk\n```\n\n### Get API Key\n\n1. Visit [AdsonAI Dashboard](https://adsonai.vercel.app/api-keys)\n2. Create a new API key\n3. Copy your key (starts with `adsonai_`)\n\n### Basic Usage\n\n```python\nfrom adsonai_sdk import AdsonAI\n\n# Initialize client\nclient = AdsonAI(api_key=\"your_adsonai_api_key\")\n\n# Get contextual ads\nads = client.get_contextual_ads(\"I need running shoes\", max_ads=3)\n\n# Display results\nfor ad in ads:\n print(f\"\ud83c\udff7\ufe0f {ad.brand_name} - {ad.product_name}\")\n print(f\"\ud83d\udcac {ad.ad_text}\")\n print(f\"\ud83d\udcb0 Bid: ${ad.bid_amount}\")\n if ad.landing_url:\n print(f\"\ud83d\udd17 {ad.landing_url}\")\n print()\n\nclient.close()\n```\n\n## \ud83d\udcd6 Documentation\n\n### AdsonAI Class\n\n#### `AdsonAI(api_key, base_url=None, timeout=30)`\n\nInitialize the AdsonAI client.\n\n**Parameters:**\n- `api_key` (str): Your AdsonAI API key\n- `base_url` (str, optional): Custom API base URL\n- `timeout` (int, optional): Request timeout in seconds\n\n#### `test_connection()`\n\nTest connection to the AdsonAI API.\n\n**Returns:** `bool` - True if successful\n\n#### `get_contextual_ads(query, max_ads=3, context=None)`\n\nGet contextual ads using AI matching.\n\n**Parameters:**\n- `query` (str): User query or conversation context\n- `max_ads` (int): Maximum ads to return (1-10)\n- `context` (dict, optional): Additional context for matching\n\n**Returns:** `List[Ad]` - List of matched ads\n\n### Ad Object\n\n**Properties:**\n- `id`: Unique ad identifier\n- `brand_name`: Brand or company name\n- `product_name`: Product or service name\n- `description`: Ad description\n- `ad_text`: Display text for the ad\n- `bid_amount`: Bid amount in USD\n- `landing_url`: Landing page URL (optional)\n- `target_keywords`: Target keywords\n- `status`: Ad status\n\n### Exception Handling\n\n```python\nfrom adsonai_sdk import AdsonAI, AuthenticationError, APIError, ValidationError\n\ntry:\n client = AdsonAI(api_key=\"your_key\")\n ads = client.get_contextual_ads(\"search query\")\nexcept AuthenticationError:\n print(\"Invalid API key\")\nexcept APIError as e:\n print(f\"API error: {e}\")\nexcept ValidationError as e:\n print(f\"Validation error: {e}\")\n```\n\n## \ud83d\udca1 Examples\n\n### Context Manager\n\n```python\nwith AdsonAI(api_key=\"your_key\") as client:\n ads = client.get_contextual_ads(\"smart home devices\")\n for ad in ads:\n print(f\"{ad.brand_name}: {ad.ad_text}\")\n```\n\n### Convenience Function\n\n```python\nfrom adsonai_sdk import get_ads\n\n# Quick one-liner\nads = get_ads(\"your_key\", \"gaming laptop\", max_ads=5)\n```\n\n### Chatbot Integration\n\n```python\ndef get_sponsored_suggestion(user_message):\n try:\n ads = get_ads(API_KEY, user_message, max_ads=1)\n if ads:\n ad = ads[0]\n return f\"\ud83d\udca1 {ad.brand_name}: {ad.ad_text}\"\n except Exception:\n pass\n return None\n\n# In your chatbot\nuser_input = \"I need a new coffee maker\"\nsuggestion = get_sponsored_suggestion(user_input)\nif suggestion:\n print(suggestion)\n```\n\n### E-commerce Integration\n\n```python\ndef show_sponsored_products(search_query):\n with AdsonAI(api_key=API_KEY) as client:\n ads = client.get_contextual_ads(search_query, max_ads=3)\n \n print(\"\ud83c\udfaf Sponsored Products:\")\n for ad in ads:\n print(f\"\u2022 {ad.brand_name} - {ad.product_name}\")\n print(f\" {ad.ad_text}\")\n print(f\" ${ad.bid_amount} | {ad.landing_url}\")\n```\n\n## \ud83d\udd27 Advanced Usage\n\n### With Additional Context\n\n```python\ncontext = {\n 'user_location': 'San Francisco',\n 'user_age': '25-34',\n 'interests': ['fitness', 'technology'],\n 'budget': 'mid-range'\n}\n\nads = client.get_contextual_ads(\n \"workout equipment\", \n max_ads=5, \n context=context\n)\n```\n\n### Error Handling with Retries\n\n```python\nimport time\nfrom adsonai_sdk import AdsonAI, APIError\n\ndef get_ads_with_retry(query, max_retries=3):\n for attempt in range(max_retries):\n try:\n with AdsonAI(api_key=API_KEY) as client:\n return client.get_contextual_ads(query)\n except APIError as e:\n if e.status_code == 429: # Rate limit\n time.sleep(2 ** attempt) # Exponential backoff\n continue\n raise\n return []\n```\n\n## \ud83e\uddea Testing\n\n```bash\n# Set your API key\nexport ADSONAI_API_KEY=\"your_actual_api_key\"\n\n# Run tests\npython -m pytest tests/\n\n# Run integration test\npython test_live_api.py\n```\n\n## \ud83d\udcdd License\n\nMIT License - see LICENSE file for details.\n\n## \ud83e\udd1d Support\n\n- \ud83d\udcda Documentation: [https://docs.adsonai.com](https://docs.adsonai.com)\n- \ud83c\udf9b\ufe0f Dashboard: [https://adsonai.vercel.app](https://adsonai.vercel.app)\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/adsonai/python-sdk/issues)\n- \ud83d\udce7 Email: developers@adsonai.com\n\n## \ud83d\udee3\ufe0f Roadmap\n\n- [ ] Async support with `aiohttp`\n- [ ] Batch ad matching\n- [ ] Advanced analytics\n- [ ] Webhook support\n- [ ] Ad performance tracking\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for AdsonAI contextual advertising platform",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/adsonai/adsonai-python-sdk/issues",
"Documentation": "https://docs.adsonai.com",
"Homepage": "https://adsonai.com",
"Repository": "https://github.com/adsonai/adsonai-python-sdk"
},
"split_keywords": [
"advertising",
" ai",
" llm",
" contextual",
" ads",
" monetization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9e5b69219851b09764e7703638250021e671e374d8212e59a0cc705e0cd82a69",
"md5": "d4a074b6cb780829a18aea9ce1af35d6",
"sha256": "fdf43d9cd242d3a27e7b9ce8891e3e991897c7e6efbfb4c5dfc4b6a920b8c9e1"
},
"downloads": -1,
"filename": "adsonai-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4a074b6cb780829a18aea9ce1af35d6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15800,
"upload_time": "2025-08-17T16:44:07",
"upload_time_iso_8601": "2025-08-17T16:44:07.422421Z",
"url": "https://files.pythonhosted.org/packages/9e/5b/69219851b09764e7703638250021e671e374d8212e59a0cc705e0cd82a69/adsonai-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a5f659695b2854bb4b9df913bb81334c4b82ff69ff498d951cc929e4cbcb2f41",
"md5": "842ca6f3aa53cebe07ccaa0a6a2033c8",
"sha256": "21ca3c5e0f8dce145c6d6125f3dac8bc874650c75e7b37437c6d751f3833b4fb"
},
"downloads": -1,
"filename": "adsonai-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "842ca6f3aa53cebe07ccaa0a6a2033c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20273,
"upload_time": "2025-08-17T16:44:09",
"upload_time_iso_8601": "2025-08-17T16:44:09.102962Z",
"url": "https://files.pythonhosted.org/packages/a5/f6/59695b2854bb4b9df913bb81334c4b82ff69ff498d951cc929e4cbcb2f41/adsonai-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 16:44:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adsonai",
"github_project": "adsonai-python-sdk",
"github_not_found": true,
"lcname": "adsonai"
}
JSON
