بررسی
سرویس نتایج گوگل جستجوی گوگل را برای شما انجام می‌دهد. یک دامنه و یک کلمهٔ کلیدی می‌دهید، این سرویس نتایج گوگل را برای همان عبارت می‌خواند و سندی ساختاریافته از آن برمی‌گرداند — رتبهٔ دامنهٔ شما، فهرست نتایج، و هر چیزی که گوگل کنارشان گذاشته است.
این سرویس برای برنامه‌هایی است که داده را در کد خودشان مصرف می‌کنند — همان چیزی که کنسول پایش رصد به‌جای شما انجام می‌دهد.
| مورد | مقدار |
|---|---|
| نشانی پایه | https://serp.rasaad.ir |
| اندپوینت‌های پیشنهادی | /api/v1/operator/* |
| نوع محتوا | application/json مگر خلافش گفته شود |
| احراز هویت | فقط کلید API |
سه کاری که سرویس نتایج گوگل انجام می‌دهد
ثبت یک پرس‌وجو
یک خزش را همین حالا اجرا می‌کند. هیچ زمان‌بندی‌ای نمی‌سازد و هیچ اثر جانبی ندارد.
خواندن نتایج
نتایج خزش‌های تمام‌شده را می‌دهد؛ به‌صورت سند خام، به شکل قالب سازگار با SerpAPI، یا به‌صورت markdown و HTML خام.
رهگیری یک پرس‌وجو در طول زمان
یک «هدف» می‌سازید تا همان پرس‌وجو روی زمان‌بندی تکرار شود و تاریخچهٔ رتبه در دستتان باشد.
تفاوت این سه با یک جدول، چون اشتباه‌شان هزینه دارد:
| کار | اندپوینت | اثر جانبی |
|---|---|---|
| اجرای یک‌باره | POST /queries | هیچ — نه هدفی می‌سازد، نه زمان‌بندی‌ای |
| رهگیری مداوم | POST /targets | یک زمان‌بندی دائمی می‌سازد |
| خواندن | GET /results | هیچ |
POST /api/query، گذاشتن cadence_hours بزرگ‌تر از صفر بیسروصدا یک هدف تکرارشونده
می‌ساخت؛ یک upsert پنهان داخل یک درخواست ثبت. اگر از مسیر قدیمی مهاجرت می‌کنید، این را
بدانید. جزئیات در مسیرهای قدیمی.شروع سریع
KEY=kserp_...
# ۱. این کلید چه می‌تواند بکند و سقف‌هایش چیست؟
curl -s -H "X-API-Key: $KEY" \
https://serp.rasaad.ir/api/v1/operator/capabilities
# ۲. همین حالا یک پرس‌وجو اجرا کن (بدون زمان‌بندی و بدون اثر جانبی)
curl -s -X POST -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
-d '{"domain":"example.ir","keyword":"shoes","city":"tehran"}' \
https://serp.rasaad.ir/api/v1/operator/queries
# ۳. همان پرس‌وجو را زمان‌بندی کن (هر ۶ ساعت)
curl -s -X POST -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
-d '{"domain":"example.ir","keyword":"shoes","city":"tehran","cadence_hours":6}' \
https://serp.rasaad.ir/api/v1/operator/targets
# ۴. اجراهای تمام‌شده را بخوان
curl -s -H "X-API-Key: $KEY" \
"https://serp.rasaad.ir/api/v1/operator/results?domain=example.ir&keyword=shoes"
دسته اندپوینت
هر دو دسته پشتیبانی می‌شوند و هیچ‌کدام منسوخ اعلام نشده‌اند.
| موضوع | API منابع | مسیر قدیمی |
|---|---|---|
| پیشوند | /api/v1/operator/* | /api/* |
| مدل | منبع: targets، queries، results، usage | کنشی: «ثبت کن»، «بخوان» |
| احراز هویت | فقط کلید API | کلید API یا کوکی نشست داشبورد |
| صفحه‌بندی | limit + کرسر امضاشده، با total | فقط limit |
| فیلتر وضعیت | دارد | ندارد |
| محدودیت نرخ | دارد | ندارد |
در یکپارچگی تازه از API منابع استفاده کنید. مسیرهای قدیمی برای کلاینت‌هایی است که همین حالا نوشته شده‌اند.
GET /api/results هیچ معادلی در v1 ندارد، چون
/api/v1/operator/results مسیر منابعِ کاملتری است و این دو یک پرس‌وجو نیستند.
مقایسهٔ کامل در مسیرهای قدیمی.اول کلیدتان را بپرسید
قبل از هر چیز دیگر، GET /capabilities را فراخوانی کنید. به یک کلید معتبر نیاز دارد و هیچ
دسترسی خاصی لازم ندارد:
curl -s -H "X-API-Key: $KEY" \
https://serp.rasaad.ir/api/v1/operator/capabilities
تا وقتی ندانید چه کلیدی دارید، نمی‌توانید بپرسید با آن چه کارهایی می‌توانید بکنید. این تنها اندپوینتی است که به هیچ دسترسی خاصی نیاز ندارد.
سه مفهومی که باید از هم جدا نگه دارید
| مفهوم | یعنی چه | شناسه‌اش |
|---|---|---|
| پرس‌وجو | یک اجرای خزش | task_id |
| هدف | یک پرس‌وجوی زمان‌بندی‌شدهٔ دائمی | target_id |
| نتیجه | سند آنچه خزش در آن لحظه دید | task_id |
نقشهٔ راهنما
| صفحه | موضوع |
|---|---|
| احراز هویت | ارسال کلید، جدول دسترسی‌ها، مالکیت داده، و 401 در برابر 403 در برابر 404 |
| اهداف | چرخهٔ کامل هدف: ساخت، فهرست، ویرایش، روشن/خاموش، حذف، تاریخچه |
| پرس‌وجوها | اجرای یک‌باره، مدل وضعیت و معنای deduped |
| نتایج | سند نتیجه، قالب SerpAPI، نمایش markdown و HTML خام، و صفحه‌بندی روی مرزهای واقعی |
| مصرف | شمارنده‌های یک دوره و اینکه چرا quota همیشه null است |
| محدودیت نرخ | سطل توکن، هدرها و رفتار در 429 |
| صفحه‌بندی | کرسر امضاشده و چرا keyset است، نه offset |
| مرجع خطاها | هر کد وضعیت و معنای آن |
| مسیرهای قدیمی | /api/*، تفاوت‌ها، و GET /selector-health |