‏Web Search اپیفای: نتایج گوگل به شکل JSON برای ایجنت‌ها

Apify یه Actor (یعنی یه برنامه‌ی آماده که روی پلتفرم Apify اجرا می‌شه) به اسم Web Search منتشر کرده که نتایج ارگانیک جستجو رو به شکل JSON برمی‌گردونه. هر نتیجه title، URL، snippet و position داره. ایده اینه که بتونی بهش به چشم یه ابزار جستجو برای ایجنت یا اپ LLM نگاه کنی، یا از هر اسکریپت و بک‌اندی صداش بزنی.

کار کردن باهاش ساده‌ست. یه درخواست GET یا POST به می‌فرستی و فقط فیلد query اجباریه. جواب همون لحظه تو همون درخواست برمی‌گرده، یعنی نه polling لازمه و نه endpoint جدا برای گرفتن نتیجه. Apify خودش هاستینگ، پروکسی و چرخوندن IP رو مدیریت می‌کنه. توکن رو هم می‌شه تو query یا هدر Authorization: Bearer فرستاد، ولی خود Apify می‌گه هدر امن‌تره چون URLها ممکنه تو لاگ‌ها بمونن.

فیلترها هم کامل هستن. با provider بین google (پیش‌فرض) و duckduckgo انتخاب می‌کنی. countryCode و languageCode ترتیب نتایج رو بر اساس کشور و زبان عوض می‌کنن. dateFrom و dateTo بازه‌ی تاریخ انتشار رو مشخص می‌کنن و allowedDomains و فیلد مقابلش برای حذف دامنه‌ها هر کدوم تا 10 دامنه قبول می‌کنن. یه دامنه زیردامنه‌هاش رو هم شامل می‌شه، مثلاً wikipedia.org با en.wikipedia.org هم match می‌شه. البته فیلتر تاریخ به سیگنال‌های خود موتور جستجو وابسته‌ست و ممکنه دقیق نباشه.

فرق دو موتور هم مهمه. گوگل location رو پشتیبانی می‌کنه و جزئیات بیشتری مثل date، siteName و siteLinks می‌ده. DuckDuckGo فقط یه صفحه با حدود 10 نتیجه برمی‌گردونه و اگه بهش location بدی خطای INVALID_PARAMETER می‌گیری. تو مستندات پیشنهاد شده اگه گوگل چیزی پیدا نکرد یا fail شد، DuckDuckGo رو امتحان کنی.

یه سرور MCP (یعنی Model Context Protocol، استانداردی برای وصل کردن ابزار به مدل‌های زبانی) هم روی مسیر /mcp هست که فقط یه ابزار به اسم search داره و می‌شه مستقیم تو Claude Code یا Cursor اضافه‌ش کرد. قیمت‌گذاری pay-per-event ـه، یعنی هر جستجوی موفق یه بار حساب می‌شه، حتی اگه نتیجه‌ای نداشته باشه. جستجوهای ناموفق مثل timeout یا ورودی نامعتبر پولی نیستن و maxResults هم رو قیمت اثری نداره.

نکات کلیدی:

• قیمت از 1 دلار برای هر 1000 نتیجه‌ی جستجوی گوگل شروع می‌شه
• فقط فیلد query اجباریه و جواب تو همون درخواست HTTP برمی‌گرده
• فیلترهای دامنه، چه برای نگه داشتن و چه برای حذف، هر کدوم حداکثر 10 دامنه قبول می‌کنن
• DuckDuckGo فقط حدود 10 نتیجه می‌ده و location رو پشتیبانی نمی‌کنه
• سقف زمان هر جستجو 60 ثانیه‌ست و بعدش خطای SEARCH_TIMEOUT میاد