avito-sdk

[ 🇬🇧 English ] | 🇷🇺 Документация на русском

High-performance headless Avito scraping and data extraction SDK for Python.
Developed by core contributor to Duff89/parser_avito.

🤝 Community, Issues & Support

• 🐛 Found a bug or parser issue? Please Open an Issue — parser layout fixes and bug reports are prioritized!
• 💬 Questions, proxy setups, or feature ideas? Join our GitHub Discussions.
• ⭐ Find this SDK useful? Give it a star on GitHub — it helps more developers discover the library!
• ☕ Support development (USDT TRC-20): TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P (Verify on TronScan)

🚀 Key Features

• 🚀 100% Headless & Lightweight: Zero desktop window / GUI dependencies (No Tkinter, CustomTkinter, or Flet). Runs out of the box in Linux, Docker, AWS, Raspberry Pi, Windows, and macOS.
• ⚡ Dual Sync & Async API: AsyncAvitoClient for high-throughput asyncio backends (Aiogram 3, FastAPI, aiohttp) and AvitoClient for scripts and automation.
• 📉 Real-time Price Tracking (PR #334 / Issue #214): Built-in PriceTracker engine with SQLite persistence, historical logs, and automatic price drop calculation (item.price_drop).
• 👤 Seller Details & Store Slugs (PR #334 / Issue #333): Extracts verified seller name (seller_name) and seller profile/brand ID (seller_id).
• 📋 Deep Parameters & Specs Parsing (PR #337 / Issue #335): Extracts full item characteristics («О помещении», floor, area, auto specs, electronics) from Beduin mobile scenarios and Mobile API.
• 📝 Full Multiline Descriptions (PR #329 / Issue #305): Extracts complete uncut descriptions from JSON scenarios and Schema.org microdata.
• 🛡️ Anti-Bot TLS Fingerprinting: Browser impersonation (Chrome/Safari TLS fingerprints) via curl_cffi with transparent fallback to standard HTTP transport.
• 📊 Multi-Format Exporters: Direct export to styled Excel (.xlsx with automatic column sizing via openpyxl), CSV, JSON, JSONL, and Pandas/Polars DataFrame.
• 💻 Command-Line Interface (CLI): Built-in CLI commands avito-sdk and avito-parser for instant terminal searches and exports.
• 🌐 Universal Python Support: Full compatibility with Python 3.8 – 3.16+, Free-Threaded No-GIL (PEP 703: 3.13t–3.15t), and PyPy.

📦 Installation

# Standard installation via PyPI
pip install avito-sdk

# With anti-bot TLS impersonation (recommended)
pip install "avito-sdk[tls]"

# Full installation (Excel, TLS, Async, DataFrames)
pip install "avito-sdk[all]"

Via Debian / Ubuntu APT (eminsk PPA)

curl -sS https://eminsk.github.io/ppa/setup.sh | sudo bash
sudo apt install python3-avito-sdk

Or via Conda / Mamba:

conda install -c conda-forge avito-sdk
# or with pixi
pixi add avito-sdk

🌟 What's New in Version 0.2.0 (Release 0.2.0)

• 🔄 Automatic Block Recovery (Auto-Failover): Automatically detects HTTP 429 / SmartCaptcha challenges, triggers mobile proxy IP rotation via MobileProxy.space, drops dead TCP sockets, and recovers scraping seamlessly with 100% success.
• 📱 Realistic Android User-Agent Pool: Dynamic rotation of modern Android devices (Pixel 8, Galaxy S23/S24, Xiaomi 13/14) with synchronized Client Hints (sec-ch-ua, sec-ch-ua-platform="Android") perfectly matched to Chrome 131 TLS impersonation.
• 🔗 Direct Search by Catalog URLs: client.search() now natively accepts pasted Avito catalog/search URLs with delivery and sorting filters.
• 📊 Clickable Links in Excel Reports: Automatically formats column 9 as blue clickable hyperlinks (https://www.avito.ru/...).
• 🤖 Interactive Telegram Bot: Built-in /code command and UI button in @eminsk_avito_bot for instant code retrieval in private chats.
• 🧵 Modem Concurrency Safety: Safe concurrency limiter (sanitize_workers) enforcing max 2 threads per mobile modem to prevent WAF bans.

⚡ Quickstart (Minimal 3-line code without boilerplate)

1. Installation:

uv add avito-sdk
# or: pip install avito-sdk

2. Scraping without main() functions:

from avito_sdk import AvitoClient

# Initialize client with your mobile proxy
client = AvitoClient(
    proxy="http://user:password@host:port",
    proxy_change_url="https://changeip.mobileproxy.space/?proxy_key=...",
    modems_count=1,
)

# 1. Search by query or direct Avito URL
for item in client.search("RTX 4090", limit=10, show_progress=True):
    print(f"{item.title} | {item.price:,} ₽ | {item.url}")
    print(f"  Seller: {item.seller_name} | Views: {item.total_views}")

# 2. Or scrape catalog link directly into styled Excel (.xlsx) report
client.scrape_url(
    url="https://www.avito.ru/moskva/noutbuki?cd=1",
    limit=30,
    enrich_details=True,
    excel_path="noutbuki.xlsx",
)

2. Asynchronous Streaming (Telegram Bots & FastAPI)

import asyncio
from avito_sdk import AsyncAvitoClient

async def main():
    async with AsyncAvitoClient() as client:
        async for item in client.search("rtx 4070", region="sankt-peterburg", limit=20):
            print(f"Found: {item.title} ({item.price:,} ₽) -> {item.url}")

asyncio.run(main())

3. Extracting Detailed Parameters & Specs (PR #337)

from avito_sdk import AvitoClient

client = AvitoClient()

# Fetch rich item card with all specs
item = client.get_item(1234567890)

print("Title:", item.title)
print("Price:", item.price)
print("Seller:", item.seller_name)
print("Views:", f"{item.total_views} total, {item.today_views} today")

print("\nParameters (PR #337):")
for param_name, param_val in item.params.items():
    print(f"  • {param_name}: {param_val}")

print("\nDescription (PR #329):")
print(item.description)

4. Tracking Price Drops (PR #334)

from avito_sdk import AvitoClient

client = AvitoClient(tracker_db="prices.db")

# Scrape listings with automated price tracking
items = list(client.search("iPhone 15 Pro", region="moskva", limit=50))

# Query recorded price drops:
drops = client.tracker.get_price_drops()
for drop in drops:
    diff = drop["initial_price"] - drop["current_price"]
    print(f"📉 Deal! {drop['title']}: {drop['initial_price']:,} -> {drop['current_price']:,} ₽ (-{diff:,} ₽)")

5. Export to Excel, JSON & Pandas

from avito_sdk import AvitoClient, to_excel, to_json, to_dataframe

client = AvitoClient()
items = list(client.search("PlayStation 5", limit=30, enrich_details=True))

# 1. Styled Excel spreadsheet with auto-width columns
to_excel(items, "ps5_listings.xlsx")

# 2. JSON Lines for data pipelines and ML
to_json(items, "ps5_listings.json")

# 3. Pandas DataFrame
df = to_dataframe(items)
print(df[["id", "title", "price", "seller_name"]].head())

6. 🌐 Mobile Proxies & Multithreading: MobileProxy.space Integration

📱 Recommended Provider: MobileProxy.space (Get a Free 3-Hour Trial)
Dedicated 4G/LTE mobile proxies across real SIM carriers (MTS, Megafon, Beeline, Tele2) with instant URL/API IP rotation.

Option A: One-line setup via mobileproxy_key

from avito_sdk import AvitoClient

# Pass your proxy address and rotation key from the MobileProxy.space dashboard
client = AvitoClient(
    proxy="http://username:password@proxy-domain.space:8000",
    mobileproxy_key="YOUR_ROTATION_KEY",  # avito-sdk builds changeip.mobileproxy.space automatically
)

# Run multithreaded card enrichment (8 parallel threads) safely via mobile proxy
items = list(
    client.search(
        query="коммерческая недвижимость",
        region="moskva",
        enrich_details=True,  # Fetches full params («О помещении»), views & description
        max_workers=8,        # Parallel threads (requires mobile proxy!)
        limit=100,
    )
)

Option B: Standalone IP rotation via MobileProxySpace

from avito_sdk import MobileProxySpace

mps = MobileProxySpace.from_key("YOUR_ROTATION_KEY")
res = mps.rotate_ip(wait_reconnect=True)
print("New public IP:", res.get("new_ip"))

Option C: From Terminal CLI

avito-sdk search "ноутбук" --proxy "http://user:pass@host:port" --mobileproxy-key "YOUR_KEY" --enrich --workers 4

7. 🎭 Playwright Cookie Harvesting + Telegram Progress Bar + Excel Upload

Install with Playwright browser support (pip install "avito-sdk[all]"):

from avito_sdk import AvitoClient

client = AvitoClient(
    proxy="http://user:pass@ip:port",
    proxy_change_url="https://changeip.mobileproxy.space/?proxy_key=YOUR_KEY",
    use_playwright_cookies=True,  # Automatically harvests 'ft' cookie via headless Chromium + stealth JS
    tg_token="123456:ABC-DEF_BOT_TOKEN",
    tg_chat_id="-1001234567890",  # Telegram channel or chat ID
)

# Scrapes with mobile proxy, updates a live progress bar in Telegram,
# sends formatted cards (📉 Old ➔ New price), saves styled .xlsx, and uploads the .xlsx to Telegram!
items = list(
    client.search(
        query="аренда склада",
        region="moskva",
        enrich_details=True,
        max_workers=4,
        limit=50,
        notify_telegram=True,
        telegram_progress=True,
        show_progress=True,
        excel_path="warehouses.xlsx",
    )
)

Live status message displayed in Telegram during scraping:

⏳ Парсинг Авито: аренда склада
🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜ 50% (25/50)
🌐 Мобильный прокси: Активен (ротаций IP: 2)
🧵 Потоков: 4  |  📉 Снижений цен: 3

8. 🤖 Interactive Telegram Bot Controller (AvitoTelegramBot)

Control parsing directly from Telegram (/search, /proxy, /workers, /playwright), watch a live updating progress bar (🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜ 50%), and receive the .xlsx report right in the chat:

from avito_sdk import AvitoTelegramBot

bot = AvitoTelegramBot(
    bot_token="123456:ABC-DEF_BOT_TOKEN",
    proxy="http://user:pass@ip:port",
    proxy_change_url="https://changeip.mobileproxy.space/?proxy_key=YOUR_KEY",
    workers=4,
    use_playwright_cookies=True,
)
bot.run_polling()

🖥️ Command-Line Interface (CLI)

The package provides avito-sdk and avito-parser executable scripts:

# Search and save directly to Excel:
avito-sdk search "MacBook M2" --region moskva --max-price 90000 --output macbooks.xlsx

# High-speed multithreaded search with Mobile Proxy, Playwright cookies, Telegram progress & Excel upload:
avito-sdk search "помещение" --region moskva --enrich --workers 5 \
  --proxy "http://user:pass@ip:port" \
  --proxy-change-url "https://changeip.mobileproxy.space/?proxy_key=..." \
  --playwright \
  --tg-token "123456:ABC..." --tg-chat-id "-1001234567890" \
  --output premises.xlsx

# Launch interactive Telegram Bot Controller (manage proxy, workers & receive .xlsx in Telegram):
avito-sdk bot --tg-token "123456:ABC..." \
  --proxy "http://user:pass@ip:port" \
  --proxy-change-url "https://changeip.mobileproxy.space/?proxy_key=..." \
  --playwright --workers 4

# Run directly from a parser_avito config.toml file:
avito-sdk config config.toml

# Inspect single item card:
avito-sdk item 3854129841

# View all recorded price drops:
avito-sdk drops --db prices.db

# Start Model Context Protocol (MCP) Server over stdio:
avito-mcp --proxy "http://user:pass@ip:port" --proxy-change-url "https://..." --playwright

🤖 Native MCP (Model Context Protocol) Server

Connect avito-sdk directly to Claude Desktop, Cursor, Windsurf, or Antigravity via the built-in avito-mcp (avito-sdk mcp) JSON-RPC 2.0 server (avito_search, avito_get_item, avito_price_drops):

{
  "mcpServers": {
    "avito": {
      "command": "avito-mcp",
      "args": ["--playwright", "--workers", "4"],
      "env": {
        "AVITO_PROXY": "http://user:pass@ip:port",
        "AVITO_PROXY_CHANGE_URL": "https://changeip.mobileproxy.space/?proxy_key=YOUR_KEY"
      }
    }
  }
}

🛠️ Comparison: parser_avito (GUI) vs avito-sdk (Library)

🌐 High-Performance Systems Ecosystem

avito-sdk is developed by @eminsk as part of an open-source AI & systems engineering ecosystem:

• ⚡ NanoVector — Bare-metal C99/AVX2 vector search & episodic memory engine (~120KB) with Native MCP Server (pip install nanovector).
• 🧠 AgentJIT — Just-In-Time Compiler for AI Agent Trajectories with speculative de-optimization guards (pip install agentjit).
• ⚡ NanoGEMM — Bare-metal AVX2+FMA SIMD matrix multiplication engine in ~100KB for sub-microsecond CPU inference (pip install nanogemm).
• 🖥️ NanoRecall — 100% Private, offline desktop memory & semantic screen search engine powered by NanoVector (pip install nanorecall).
• 📈 yfinance-ta-patterns — Candlestick & chart pattern scanner with AI Confluence Scoring, Backtesting, and Native MCP Server (pip install yfinance-ta-patterns).
• 📊 xlsx_vievers — Headless Excel formula engine (129+ functions), desktop spreadsheet viewer, SIMD SSE2 math, and Native MCP Server (pip install xlsx-viewer-pro).

☕ Support, Community & Donations

If you find this project valuable, encounter issues, or want to support ongoing development:

• ⭐ Star the Repository: If avito-sdk powers your scraping or bots, give us a star on GitHub — it helps more developers discover the SDK!
• 🐛 Report Issues & Bugs: Found a bug or did Avito update their layout? Please open an Issue with reproduction details!
• 💬 Join Discussions: Have feature ideas, architecture questions, or general feedback? Start or join a thread in GitHub Discussions!
• ☕ Donate (USDT TRC-20):
  TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P
  (Network: TRON / TRC-20 | Verify on TronScan)

📄 License

Distributed under the MIT License.
Author: eminsk (M_N_Nik@yahoo.com)