اهداف

هدف یعنی یک پرس‌وجو که روی زمان‌بندی تکرار می‌شود. اگر می‌خواهید بدانید رتبهٔ یک دامنه برای یک عبارت در طول زمان چه بوده، چیزی که می‌خواهید یک هدف است.

هر بار که هدف اجرا می‌شود، یک پرس‌وجو تولید می‌کند، و آن پرس‌وجو به‌مرور نتیجه می‌سازد.

هویت یک هدف سه‌تایی است

هویت یک هدف برابر است با:

(domain, keyword, city)

برای همین، فرستادن دوبارهٔ همان سه‌تایی به‌روزرسانی می‌کند و تکراری نمی‌سازد. اگر کلاینت درخواست را دوباره بفرستد، زمان‌بندی دومی ساخته نمی‌شود.

ساخت هدف

POST /targets → 201 — نیازمند targets:write.

یک هدف تازه می‌سازد، یا اگر همان سه‌تایی از قبل هست آن را به‌روز می‌کند.

نمونهٔ درخواست:

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

نمونهٔ پاسخ:

{"ok": true, "target_id": 12, "created": true, "target": { … }}

target_id شناسهٔ هدف است و در بقیهٔ مسیرهای همین صفحه استفاده می‌شود. فیلد created به شما می‌گوید این تازه ساخته شده یا به‌روزرسانی بود.

فهرست هدف‌ها

GET /targets — نیازمند targets:read.

همهٔ هدف‌های شما، مرتب بر اساس id صعودی.

نمونهٔ درخواست:

curl -s -H "X-API-Key: $KEY" \
  "https://serp.rasaad.ir/api/v1/operator/targets?limit=50"

نمونهٔ پاسخ:

{"ok": true, "rows": [ … ], "total": 12, "next_cursor": "…"}

هر ردیف یک هدف است:

{
  "id": 12, "domain": "example.ir", "keyword": "shoes", "city": "tehran",
  "cadence_hours": 6.0, "enabled": true, "pages": 1,
  "expand_answers": 0, "owner": "acme"
}

گرفتن یک هدف

GET /targets/{target_id} — نیازمند targets:read.

یک هدف را با شناسه‌اش برمی‌گرداند.

نمونهٔ درخواست:

curl -s -H "X-API-Key: $KEY" \
  https://serp.rasaad.ir/api/v1/operator/targets/12

نمونهٔ پاسخ:

{"ok": true, "target": { … }}

ویرایش هدف

PATCH /targets/{target_id} — نیازمند targets:write (و اگر بدنه enabled را ست کند، اضافه بر آن targets:delete هم لازم است).

فقط فیلدهایی که می‌فرستید عوض می‌شوند؛ بقیه دست‌نخورده می‌مانند.

نمونهٔ درخواست:

curl -s -X PATCH -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"cadence_hours":12}' \
  https://serp.rasaad.ir/api/v1/operator/targets/12

نمونهٔ پاسخ:

{"ok": true, "target": { … }}

اگر عملاً چیزی تغییر نکرده باشد پاسخ 404 است، تا بتوانید بفهمید ویرایش اعمال شد یا نه.

روشن و خاموش کردن

POST /targets/{target_id}/enable و POST /targets/{target_id}/disable — هر دو نیازمند targets:delete.

هدف را روشن یا خاموش می‌کند بدون اینکه حذفش کند.

نمونهٔ درخواست:

curl -s -X POST -H "X-API-Key: $KEY" \
  https://serp.rasaad.ir/api/v1/operator/targets/12/disable

نمونهٔ پاسخ:

{"ok": true, "enabled": false, "queued_dropped": 2, "target": { … }}

خاموش‌کردن، کارهای در صف آن هدف را لغو می‌کند و تعدادشان را در queued_dropped گزارش می‌دهد.

حذف هدف

DELETE /targets/{target_id} — نیازمند targets:delete.

هدف را حذف می‌کند. پارامتر اختیاری ?with_history=1 تاریخچهٔ رتبه را هم پاک می‌کند.

نمونهٔ درخواست:

curl -s -X DELETE -H "X-API-Key: $KEY" \
  https://serp.rasaad.ir/api/v1/operator/targets/12

نمونهٔ پاسخ:

{"ok": true, "target_id": 12, "queued_dropped": 0, "history_deleted": false}

تاریخچهٔ رتبه

GET /targets/{target_id}/history — نیازمند targets:read.

رتبهٔ یک هدف در طول زمان، جدیدترین اول.

نمونهٔ درخواست:

curl -s -H "X-API-Key: $KEY" \
  "https://serp.rasaad.ir/api/v1/operator/targets/12/history?limit=200"

?since= و ?until= ثانیهٔ epoch هستند و روی finished فیلتر می‌کنند. اینها فیلتر هستند، هرگز کرسر صفحه‌بندی نیستند.

نمونهٔ پاسخ:

{
  "ok": true, "target_id": 12,
  "rows": [
    {"task_id": "5fa4d2c1", "keyword": "shoes", "city": "tehran", "domain": "example.ir",
     "bot_id": "tehran-…", "rank": 2, "previous_rank": 4, "rank_change": 2,
     "pages": 2, "finished": 1767225600.0, "out_path": "…"}
  ],
  "count": 1
}

out_path را استفاده نکنید؛ نتایج را با task_id بخوانید.

خلاصه