OpenAPI سئو سیگنال

دسترسی برنامه‌نویسی به ابزارهای تحقیق کلمه کلیدی و آنالیز کلمات سایت — برای اتوماسیون گزارش‌ها و اتصال به ابزارهای خودتان، بدون باز کردن پنل.

پایه آدرس: /openapi/v1/ قالب: JSON احراز هویت: X-Api-Key

معرفی

این API همان منطق و داده‌ای را برمی‌گرداند که در پنل سئو سیگنال می‌بینید — تحقیق کلمه کلیدی، آنالیز کلمات سایت، دستیار رپورتاژ و ردیاب رتبه — به‌صورت درخواست‌های ساده HTTP با بدنه و پاسخ JSON. همه endpointها با متد POST فراخوانی می‌شوند و پاسخ همیشه یک شیء JSON با کلید ok است.

ⓘ

ردیاب رتبه (RankTracker) چون داده خودِ حساب شماست، مشمول سقف روزانه نیست. تحقیق کلمه کلیدی، آنالیز کلمات سایت، مقایسه سایت و دستیار رپورتاژ از یک سقف روزانه مشترک استفاده می‌کنند.

احراز هویت

کلید API خود را از منوی کاربری پنل، بخش «مدیریت API» بسازید. کلید به‌صورت ایمیل:توکن نمایش داده می‌شود — همین مقدار را عیناً در هدر هر درخواست بفرستید.

هدر درخواست
X-Api-Key: saeed@example.com:a1b2c3d4e5f6...64کاراکتر
⚠

این کلید معادل رمز عبور حساب شماست. آن را در کد سمت کلاینت (مرورگر) قرار ندهید و در صورت افشا، بلافاصله از پنل بازتولیدش کنید.

اتصال MCP

علاوه‌بر endpointهای REST بالا، همه ابزارهای این API از طریق یک سرور MCP (Model Context Protocol) هم در دسترس‌اند — برای اتصال مستقیم دستیارهای هوش مصنوعی به داده‌های سئو سیگنال، بدون نیاز به نوشتن کد. سرور MCP دقیقاً همان منطق/داده REST را برمی‌گرداند؛ فقط قالب پروتکل فرق دارد.

POST /openapi/mcp Streamable HTTP
TransportStreamable HTTP (بدون SSE) — طبق نسخه ۲۰۲۵-۰۶-۱۸ مشخصات MCP
احراز هویتهمان هدر X-Api-Key بالا
ابزارهاهر ۱۲ endpoint این صفحه، به‌صورت ابزار MCP با همان پارامترها
ⓘ

بعد از اتصال، کلاینت با متد tools/list فهرست کامل ابزارها را با شرح و پارامترهایشان خودکار کشف می‌کند — نیازی به کپی دستی مستندات نیست. سقف روزانه و دسترسی پلن (رپورتاژ/رایگان) عیناً مثل REST روی هر ابزار اعمال می‌شود. برای گفتگوی طبیعی کافی است بگویید مثلاً «از طریق MCP سئو سیگنال، رتبه سایتم رو چک کن» — دستیار خودش ابزار مناسب را صدا می‌زند.

اتصال از کلاینت‌های مختلف

از منوی Settings → Developer → Edit Config فایل پیکربندی MCP را باز کنید و این بلوک را داخل mcpServers اضافه کنید، سپس Claude Desktop را ری‌استارت کنید.

claude_desktop_config.json 
{
  "mcpServers": {
    "seosignal": {
      "url": "https://panel.seosignal.net/openapi/mcp",
      "headers": { "X-Api-Key": "YOUR_API_KEY" }
    }
  }
}

بعد از ری‌استارت، آیکون ابزارها (🔌) پایین چت باید ۱۲ ابزار سئو سیگنال را نشان دهد.

در ترمینال، داخل پوشه پروژه یا با دستور کلی زیر سرور را اضافه کنید:

ترمینال 
claude mcp add --transport http seosignal \
  https://panel.seosignal.net/openapi/mcp \
  --header "X-Api-Key: YOUR_API_KEY"

با دستور /mcp داخل Claude Code می‌توانید وضعیت اتصال و ابزارهای در دسترس را ببینید.

شروع سریع

  1. ۱

    کلید API را بسازید

    پنل → آیکون کاربری → مدیریت API → دکمه «ساخت کلید API».

  2. ۲

    یک درخواست بزنید

    نمونه‌های curl پایین هر endpoint را کپی و YOUR_API_KEY را با کلید خودتان جایگزین کنید.

  3. ۳

    پاسخ را بخوانید

    در موفقیت، ok:true و داده در کلید data برمی‌گردد. در خطا، error.code و error.message را ببینید.

سقف و مصرف روزانه

هر کاربر به‌طور پیش‌فرض روزانه ۵۰ درخواست به بخش‌های تحلیلی دارد (این عدد در پنل، بخش «مدیریت API»، همراه با میزان مصرف امروز شما قابل مشاهده است). شمارنده هر روز ساعت ۰۰:۰۰ به‌وقت تهران صفر می‌شود.

limit— سقف روزانه مؤثر شما
usage— مصرف پلن سرویس شما (جدا از سقف روزانه API)
⚠

OpenAPI برای پلن رایگان فعال نیست. اگر حساب شما در پلن رایگان باشد، همه endpointها با خطای PLAN_NOT_ALLOWED (کد ۴۰۳) پاسخ می‌دهند.

⚠

چهار endpoint «دستیار رپورتاژ» علاوه‌بر سقف بالا، نیاز به فعال بودن سرویس رپورتاژ روی پلن شما دارند؛ در غیر این‌صورت با همان خطای PLAN_NOT_ALLOWED پاسخ داده می‌شود. همچنین endpoint آنالیز خریدار رپورتاژ، مشابه آنالیز کلمات سایت، از سقف ماهانه SRLimit پلن شما هم استفاده می‌کند (فیلدهای limit/usage در پاسخ آن).

کدهای خطا

در خطا، پاسخ همیشه این ساختار را دارد و کد HTTP متناظر برمی‌گردد:

ساختار خطا 
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "سقف روزانه درخواست‌های API به پایان رسیده است."
  }
}
400
INVALID_PARAMS
پارامتر الزامی خالی است یا مقدار یکی از فیلدهای انتخابی (مثل search_type) در فهرست مجاز نیست.
401
INVALID_API_KEY
هدر X-Api-Key ارسال نشده یا کلید نامعتبر است.
403
ACCOUNT_DISABLED
حساب کاربری غیرفعال یا مسدود شده است.
403
PLAN_NOT_ALLOWED
پلن فعلی حساب شما (رایگان) اجازه استفاده از OpenAPI را ندارد.
405
METHOD_NOT_ALLOWED
متد درخواست POST نیست.
422
REQUEST_FAILED
درخواست معتبر بود اما نتیجه‌ای یافت نشد (مثلاً کلمه/دامنه بدون داده).
429
RATE_LIMIT_EXCEEDED
سقف روزانه به پایان رسیده. فیلدهای limit و used هم برمی‌گردند.

تحقیق کلمه کلیدی

حجم جستجو، رقابت و روند ماهانه یک کلمه کلیدی — با ۵ مدل مختلف جستجو.

POST /openapi/v1/keyword-research ⏱ مشمول سقف روزانه

پارامترهای بدنه

کلیدنوعتوضیح
keyword
الزامی		stringکلمه کلیدی هدف
search_type
اختیاری		stringمدل جستجو — پیش‌فرض similar
count
اختیاری		intحداکثر تعداد نتیجه — پیش‌فرض و سقف 1000

مقادیر search_type

کلمات مشابه — تا ۱۰۰۰ کلمه هم‌معنی و مرتبط با حجم جستجوی هرکدام.
تحلیل موضوعی — دسته‌بندی کلمات به «مرتبط با نیت» و «مرتبط با موضوع» به‌همراه چارت روند.
شروع‌شونده با — کلماتی که با عبارت جستجو شروع می‌شوند.
پایان‌یابنده به — کلماتی که به عبارت جستجو ختم می‌شوند.
پرسش‌ها — سوالاتی که کاربران حول این کلمه جستجو می‌کنند.

نمونه درخواست و پاسخ

curl
curl -X POST https://panel.seosignal.net/openapi/v1/keyword-research \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"سئو","search_type":"similar"}'
200 OK
{
  "ok": true,
  "search_type": "similar",
  "limit": 1000,
  "usage": 55,
  "data": {
    "wordSearchVolume": 12000,
    "allSearchVolume": 145000,
    "changeSearchVolume": 4.2,
    "keywordList": [
      { "Word": "سئو کلاه سفید", "SearchVolume": 2400, "Competition": "معمولی" }
    ],
    "chart": { "lable": ["مهر ۱۴۰۴", ...], "data": [121350, ...] },
    "domainCTR": { "Domain": ["safine.net (10%)", ...], "CTR": [10, ...] }
  }
}
curl
curl -X POST https://panel.seosignal.net/openapi/v1/keyword-research \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"سئو","search_type":"topical"}'
200 OK
{
  "ok": true,
  "search_type": "topical",
  "limit": 1000,
  "usage": 56,
  "data": {
    "wordSearchVolume": 12000,
    "allSearchVolume": 98000,
    "changeSearchVolume": -1.8,
    "keywordList": [
      { "Word": "آموزش سئو سایت", "SearchVolume": 3600, "Competition": "سخت" }
    ],
    "chart": { "lable": ["مهر ۱۴۰۴", ...], "data": [99200, ...] },
    "domainCTR": { "Domain": ["safine.net (10%)", ...], "CTR": [10, ...] }
  }
}
curl
curl -X POST https://panel.seosignal.net/openapi/v1/keyword-research \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"سئو","search_type":"starting_with"}'
200 OK
{
  "ok": true,
  "search_type": "starting_with",
  "limit": 1000,
  "usage": 57,
  "data": {
    "wordSearchVolume": 12000,
    "allSearchVolume": 41000,
    "changeSearchVolume": 6.5,
    "keywordList": [
      { "Word": "سئو چیست", "SearchVolume": 8100, "Competition": "معمولی" }
    ],
    "chart": { "lable": ["مهر ۱۴۰۴", ...], "data": [40100, ...] },
    "domainCTR": { "Domain": ["safine.net (10%)", ...], "CTR": [10, ...] }
  }
}
curl
curl -X POST https://panel.seosignal.net/openapi/v1/keyword-research \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"سئو","search_type":"ending_with"}'
200 OK
{
  "ok": true,
  "search_type": "ending_with",
  "limit": 1000,
  "usage": 58,
  "data": {
    "wordSearchVolume": 12000,
    "allSearchVolume": 15400,
    "changeSearchVolume": 2.1,
    "keywordList": [
      { "Word": "آموزش سئو", "SearchVolume": 3600, "Competition": "معمولی" }
    ],
    "chart": { "lable": ["مهر ۱۴۰۴", ...], "data": [15080, ...] },
    "domainCTR": { "Domain": ["safine.net (10%)", ...], "CTR": [10, ...] }
  }
}
curl
curl -X POST https://panel.seosignal.net/openapi/v1/keyword-research \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"سئو","search_type":"questions"}'
200 OK
{
  "ok": true,
  "search_type": "questions",
  "limit": 1000,
  "usage": 59,
  "data": {
    "wordSearchVolume": 12000,
    "allSearchVolume": 8600,
    "changeSearchVolume": 11.3,
    "keywordList": [
      { "Word": "سئو چگونه انجام می‌شود", "SearchVolume": 720, "Competition": "معمولی" }
    ],
    "chart": { "lable": ["مهر ۱۴۰۴", ...], "data": [8420, ...] },
    "domainCTR": { "Domain": ["safine.net (10%)", ...], "CTR": [10, ...] }
  }
}

تحقیق دسته‌ای کلمات کلیدی

حجم جستجو، رقابت و روند ماهانه برای چند کلمه کلیدی هم‌زمان — مناسب گزارش‌های دوره‌ای روی یک سبد کلمه.

POST /openapi/v1/keyword-research-bulk ⏱ مشمول سقف روزانه
ⓘ

یک درخواست موفق، صرف‌نظر از تعداد کلمات داخل آرایه، فقط یک واحد از سقف روزانه شما مصرف می‌کند. حداکثر ۱۰۰۰ کلمه در هر درخواست قابل ارسال است.

پارامترهای بدنه

کلیدنوعتوضیح
keywords
الزامی		string[]آرایه‌ای از کلمات کلیدی (حداکثر ۱۰۰۰ مورد)

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

curl 
curl -X POST https://panel.seosignal.net/openapi/v1/keyword-research-bulk \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["سئو","بک لینک","رپورتاژ"]}'

نمونه پاسخ

200 OK
{
  "ok": true,
  "data": {
    "wordsCount": 3,
    "allSearchVolume": 16000,
    "changeSearchVolume": 47.4,
    "keywordList": [
      { "Word": "سئو", "SearchVolume": 12000, "Competition": "معمولی" },
      { "Word": "رپورتاژ", "SearchVolume": 2400, "Competition": "معمولی" },
      { "Word": "بک لینک", "SearchVolume": 450, "Competition": "معمولی" }
    ],
    "chart": { "lable": ["مهر ۱۴۰۴", ...], "data": [18650, ...] },
    "domainCTR": { "Domain": ["safine.net (32%)", ...], "CTR": [32, ...] },
    "All": 3,
    "Count": 2,
    "Remain": 943,
    "Limit": 1000,
    "Usage": 57
  }
}

آنالیز کلمات سایت

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

POST /openapi/v1/site-analyzer ⏱ مشمول سقف روزانه

پارامترهای بدنه

کلیدنوعتوضیح
url
الزامی		stringدامنه یا آدرس هدف (مثل example.com)
search_type
اختیاری		stringمدل جستجو — پیش‌فرض domain
contains
اختیاری		stringفقط وقتی search_type=contains
count
اختیاری		intحداکثر تعداد نتیجه — پیش‌فرض و سقف 2000

مقادیر search_type

بر اساس دامنه — همه کلمات کلیدی کل دامنه.
بر اساس آدرس صفحه — کلمات کلیدی فقط همان یک صفحه.
شروع آدرس با — صفحاتی که مسیرشان با این عبارت شروع می‌شود.
آدرس شامل — صفحاتی که مسیرشان شامل عبارت contains است. در این حالت، پارامتر اضافه contains هم در بدنه درخواست الزامی است.

نمونه درخواست و پاسخ

url به‌صورت دامنه ساده — همه کلمات کلیدی کل سایت برمی‌گردد.

curl
curl -X POST https://panel.seosignal.net/openapi/v1/site-analyzer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"alibaba.ir","search_type":"domain"}'
200 OK
{
  "ok": true,
  "search_type": "domain",
  "limit": 250,
  "usage": 13,
  "data": {
    "domain": "alibaba.ir",
    "Keywords": [
      { "Word": "بلیط هواپیما", "SearchVolume": 1600, "Page": "/" }
    ],
    "topPages": [ { "Page": "/", "Avg": 4.2, "Count": 38 } ],
    "RelDomains": ["flightio.com"],
    "domainCTR": { "Domain": ["flightio.com (12%)"], "CTR": [12] }
  }
}

url به‌صورت آدرس کامل یک صفحه — فقط کلمات کلیدی همان صفحه برمی‌گردد.

curl
curl -X POST https://panel.seosignal.net/openapi/v1/site-analyzer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"alibaba.ir/flight","search_type":"page"}'
200 OK
{
  "ok": true,
  "search_type": "page",
  "limit": 250,
  "usage": 14,
  "data": {
    "domain": "alibaba.ir",
    "Keywords": [
      { "Word": "بلیط هواپیما", "SearchVolume": 1600, "Page": "/flight" }
    ],
    "topPages": [ { "Page": "/flight", "Avg": 3.1, "Count": 22 } ],
    "RelDomains": ["flightio.com"],
    "domainCTR": { "Domain": ["flightio.com (18%)"], "CTR": [18] }
  }
}

url یک مسیر پایه است — فقط صفحاتی که آدرسشان با این مسیر شروع می‌شود در نظر گرفته می‌شوند.

curl
curl -X POST https://panel.seosignal.net/openapi/v1/site-analyzer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"alibaba.ir/flight","search_type":"starting_with"}'
200 OK
{
  "ok": true,
  "search_type": "starting_with",
  "limit": 250,
  "usage": 15,
  "data": {
    "domain": "alibaba.ir",
    "Keywords": [
      { "Word": "بلیط هواپیما تهران مشهد", "SearchVolume": 880, "Page": "/flight/mashhad" }
    ],
    "topPages": [ { "Page": "/flight/mashhad", "Avg": 5.4, "Count": 9 } ],
    "RelDomains": ["flightio.com"],
    "domainCTR": { "Domain": ["flightio.com (15%)"], "CTR": [15] }
  }
}

وقتی search_type برابر contains باشد، پارامتر اضافه contains هم باید در بدنه ارسال شود؛ نتیجه فقط شامل صفحاتی می‌شود که مسیرشان حاوی این عبارت است.

curl
curl -X POST https://panel.seosignal.net/openapi/v1/site-analyzer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"alibaba.ir","search_type":"contains","contains":"flight"}'
200 OK
{
  "ok": true,
  "search_type": "contains",
  "limit": 250,
  "usage": 16,
  "data": {
    "domain": "alibaba.ir",
    "Keywords": [
      { "Word": "بلیط هواپیما", "SearchVolume": 1600, "Page": "/flight" }
    ],
    "topPages": [ { "Page": "/flight", "Avg": 3.1, "Count": 22 } ],
    "RelDomains": ["flightio.com"],
    "domainCTR": { "Domain": ["flightio.com (18%)"], "CTR": [18] }
  }
}

مقایسه دو سایت

رتبه یک مجموعه کلمه کلیدی در دو دامنه، کنار هم — برای پیدا کردن فاصله با رقیب.

POST /openapi/v1/site-compare ⏱ مشمول سقف روزانه
⚠

به‌محض معتبر بودن هر دو دامنه، مصرف هردو بلافاصله ثبت می‌شود — حتی اگر در ادامه نتیجه‌ای برنگردد. دامنه‌ها را قبل از فراخوانی مکرر بررسی کنید.

پارامترهای بدنه

کلیدنوعتوضیح
site1
الزامی		stringدامنه یا سایت اول (مبنای مقایسه)
site2
الزامی		stringدامنه یا سایت دوم (رقیب)
compare_type
اختیاری		stringمدل مقایسه — پیش‌فرض common

مقادیر compare_type

کلمات مشترک — کلماتی که هر دو سایت برایشان رتبه دارند، با رتبه هرکدام کنار هم.
رتبه‌های بهتر از — کلماتی که site1 در آن‌ها از site2 جلوتر است.
رتبه‌های بدتر از — کلماتی که site1 در آن‌ها از site2 عقب‌تر است.
کیوردگپ — کلماتی که فقط site2 رتبه دارد و site1 ندارد (فیلد Rank2 در این حالت معنا ندارد).

نمونه درخواست و پاسخ

curl
curl -X POST https://panel.seosignal.net/openapi/v1/site-compare \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site1":"alibaba.ir","site2":"flightio.com","compare_type":"common"}'
200 OK
{
  "ok": true,
  "compare_type": "common",
  "first_domain": "alibaba.ir",
  "second_domain": "flightio.com",
  "data": [
    {
      "Word": "بلیط هواپیما",
      "Rank1": 1,
      "Rank2": 2,
      "Diff": 1,
      "SearchVolume": 450
    }
  ]
}

فقط کلماتی برمی‌گردد که site1 رتبه بهتری (عدد کوچک‌تر) نسبت به site2 دارد.

curl
curl -X POST https://panel.seosignal.net/openapi/v1/site-compare \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site1":"alibaba.ir","site2":"flightio.com","compare_type":"better_than"}'
200 OK
{
  "ok": true,
  "compare_type": "better_than",
  "first_domain": "alibaba.ir",
  "second_domain": "flightio.com",
  "data": [
    {
      "Word": "بلیط هواپیما",
      "Rank1": 1,
      "Rank2": 6,
      "Diff": 5,
      "SearchVolume": 450
    }
  ]
}

فقط کلماتی برمی‌گردد که site1 رتبه بدتری (عدد بزرگ‌تر) نسبت به site2 دارد.

curl
curl -X POST https://panel.seosignal.net/openapi/v1/site-compare \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site1":"alibaba.ir","site2":"flightio.com","compare_type":"worse_than"}'
200 OK
{
  "ok": true,
  "compare_type": "worse_than",
  "first_domain": "alibaba.ir",
  "second_domain": "flightio.com",
  "data": [
    {
      "Word": "چارتر پرواز",
      "Rank1": 9,
      "Rank2": 3,
      "Diff": -6,
      "SearchVolume": 210
    }
  ]
}

کلماتی که فقط site2 برایشان رتبه دارد و site1 اصلاً رتبه‌ای ندارد — یعنی فرصت خالی برای site1. در این حالت Rank2 همیشه مقدار ثابت "!" و Diff مقدار ثابت "50<" برمی‌گرداند و معنای عددی ندارند.

curl
curl -X POST https://panel.seosignal.net/openapi/v1/site-compare \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site1":"alibaba.ir","site2":"flightio.com","compare_type":"gap"}'
200 OK
{
  "ok": true,
  "compare_type": "gap",
  "first_domain": "alibaba.ir",
  "second_domain": "flightio.com",
  "data": [
    {
      "Word": "رزرو هتل مشهد",
      "Rank1": null,
      "Rank2": "!",
      "Diff": "50<",
      "SearchVolume": 590
    }
  ]
}

پیشنهاد رسانه رپورتاژ

بر اساس تا ۴ کلمه کلیدی، رسانه‌هایی که مناسب خرید رپورتاژ برای این کلمات هستند را رتبه‌بندی می‌کند.

POST /openapi/v1/reportage-suggest ⏱ مشمول سقف روزانه
⚠

این endpoint فقط برای پلن‌هایی در دسترس است که سرویس «دستیار رپورتاژ» روی آن‌ها فعال باشد.

پارامترهای بدنه

کلیدنوعتوضیح
keywords
الزامی		string[]آرایه‌ای از کلمات کلیدی (حداکثر ۴ مورد)

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

curl 
curl -X POST https://panel.seosignal.net/openapi/v1/reportage-suggest \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["سئو","بک لینک"]}'

نمونه پاسخ

200 OK
{
  "ok": true,
  "data": [
    {
      "Domain": "blog.example-media.ir",
      "Score": 33,
      "Count": 48,
      "RankAvg": 9,
      "Price": 3700000,
      "Ranks": [
        { "Keyword": "سئو چیست", "URL": "/what-is-seo/", "Rank": 3 }
      ]
    }
  ]
}

جزئیات رسانه پیشنهادی

پروفایل لینک‌های خروجی یک رسانه (از پاسخ پیشنهاد رسانه) روی کلمات مشخص — برای بررسی این‌که آیا آن رسانه قبلاً روی این کلمات/انکرها رپورتاژ فروخته یا نه.

POST /openapi/v1/reportage-suggest-check ⏱ مشمول سقف روزانه
⚠

این endpoint فقط برای پلن‌هایی در دسترس است که سرویس «دستیار رپورتاژ» روی آن‌ها فعال باشد.

پارامترهای بدنه

کلیدنوعتوضیح
domain
الزامی		stringدامنه رسانه (از فیلد Domain در پاسخ پیشنهاد رسانه)
keywords
الزامی		string[]آرایه‌ای از کلمات کلیدی (حداکثر ۴ مورد)

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

curl 
curl -X POST https://panel.seosignal.net/openapi/v1/reportage-suggest-check \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"blog.example-media.ir","keywords":["سئو","بک لینک"]}'

نمونه پاسخ

200 OK
{
  "ok": true,
  "data": [
    {
      "FromUrl": "https://blog.example-media.ir/seo-guide/",
      "AnchorText": "آموزش سئو",
      "ToUrl": "https://alibaba.ir/seo",
      "ToHost": "alibaba.ir",
      "Follow": true
    }
  ]
}

آنالیز فروشنده رپورتاژ

یک دامنه را به‌عنوان «فروشنده» رپورتاژ بررسی می‌کند — چه رپورتاژهایی منتشر کرده، به کجا لینک داده و رتبه‌بندی خودش در گوگل چگونه است.

POST /openapi/v1/reportage-seller ⏱ مشمول سقف روزانه
⚠

این endpoint فقط برای پلن‌هایی در دسترس است که سرویس «دستیار رپورتاژ» روی آن‌ها فعال باشد.

پارامترهای بدنه

کلیدنوعتوضیح
domain
الزامی		stringدامنه رسانه هدف
report_type
اختیاری		stringنوع گزارش — پیش‌فرض reportages
date_range
اختیاری		stringبازه زمانی — پیش‌فرض all (فقط برای گزارش‌های غیر از serp اثر دارد)

مقادیر report_type

رپورتاژهای منتشرشده — لیست مقالات اسپانسری که این رسانه منتشر کرده، با عنوان، تاریخ انتشار و تعداد لینک هر مقاله.
دامنه‌های خروجی — دامنه‌هایی که این رسانه در مقالاتش به آن‌ها لینک داده.
انکرهای خروجی — متن انکرهایی که در لینک‌های خروجی استفاده شده.
صفحات لینک‌دار — صفحاتی از این رسانه که حاوی لینک خروجی هستند.
رسانه‌های هم‌رنج — دامنه‌های دیگری که روی همان آی‌پی میزبانی می‌شوند (تشخیص شبکه‌های PBN).
سرپ — کلمات کلیدی و صفحات برتر خودِ این دامنه در نتایج گوگل (همان داده آنالیز کلمات سایت). در این حالت پارامتر date_range اثری ندارد.

نمونه درخواست و پاسخ

curl
curl -X POST https://panel.seosignal.net/openapi/v1/reportage-seller \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"blog.example-media.ir","report_type":"reportages","date_range":"last_90"}'
200 OK
{
  "ok": true,
  "report_type": "reportages",
  "data": {
    "Reportages": [
      {
        "Url": "https://blog.example-media.ir/travel-tips/",
        "Follow": 6,
        "NoFollow": 0,
        "All": 6,
        "InLinkCount": 28,
        "OutDomainCount": 7,
        "OutLinkCount": 7,
        "PublishDate": "1404/02/14",
        "Title": "۱۰ نکته کاربردی سفر — بلاگ رسانه نمونه"
      }
    ]
  }
}
curl
curl -X POST https://panel.seosignal.net/openapi/v1/reportage-seller \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"blog.example-media.ir","report_type":"out_domains","date_range":"last_90"}'
200 OK
{
  "ok": true,
  "report_type": "out_domains",
  "data": {
    "OutDomains": [
      { "DomainName": "alibaba.ir", "Follow": 2, "NoFollow": 0, "All": 2 }
    ]
  }
}
curl
curl -X POST https://panel.seosignal.net/openapi/v1/reportage-seller \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"blog.example-media.ir","report_type":"serp"}'
200 OK
{
  "ok": true,
  "report_type": "serp",
  "data": {
    "domain": "blog.example-media.ir",
    "url": "https://blog.example-media.ir",
    "keywordCount": 2000,
    "topKeywords": [
      { "Word": "آموزش سئو", "SearchVolume": 3600 }
    ],
    "topPages": [ { "Page": "/seo-guide/", "Avg": 4.2, "Count": 15 } ],
    "domainCTR": { "Domain": ["translate.google.com (16%)", ...], "CTR": [16, ...] }
  }
}

آنالیز خریدار رپورتاژ

یک دامنه را به‌عنوان «خریدار» رپورتاژ بررسی می‌کند — چه رپورتاژهایی خریده، از چه رسانه‌هایی و با چه هزینه‌ای.

POST /openapi/v1/reportage-buyer ⏱ مشمول سقف روزانه + سقف SRLimit
⚠

این endpoint فقط برای پلن‌هایی در دسترس است که سرویس «دستیار رپورتاژ» روی آن‌ها فعال باشد. علاوه‌بر سقف روزانه OpenAPI، از سقف ماهانه مشترک SRLimit (همان سقف آنالیز کلمات سایت) هم استفاده می‌کند.

پارامترهای بدنه

کلیدنوعتوضیح
domain
الزامی		stringدامنه هدف (خریدار رپورتاژ)
report_type
اختیاری		stringنوع گزارش — پیش‌فرض reportages
date_range
اختیاری		stringبازه زمانی — پیش‌فرض all
search_type
اختیاری		stringمدل جستجو — پیش‌فرض domain

مقادیر report_type

رپورتاژهای دریافتی — لیست مقالات اسپانسری خریداری‌شده برای این دامنه.
رسانه‌های ورودی — رسانه‌هایی که به این دامنه رپورتاژ فروخته‌اند.
صفحات لینک‌دار — صفحاتی از این دامنه که از رپورتاژها لینک دریافت کرده‌اند.
انکرهای ورودی — متن انکرهایی که در رپورتاژهای خریداری‌شده استفاده شده.
تحلیل هزینه — روند هزینه تخمینی خرید رپورتاژ در بازه‌های ماهانه/سالانه.

مقادیر search_type

بر اساس دامنه — تحلیل روی کل دامنه انجام می‌شود.
بر اساس آدرس صفحه — تحلیل فقط روی یک صفحه خاص از دامنه انجام می‌شود؛ در این حالت domain باید آدرس کامل همان صفحه باشد.

نمونه درخواست و پاسخ

curl
curl -X POST https://panel.seosignal.net/openapi/v1/reportage-buyer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"alibaba.ir","report_type":"reportages"}'
200 OK
{
  "ok": true,
  "report_type": "reportages",
  "limit": 250,
  "usage": 19,
  "data": {
    "PRList": [
      {
        "Url": "https://news-example.ir/hotel-booking-tips",
        "FromHost": "news-example.ir",
        "Follow": 1,
        "NoFollow": 0,
        "All": 1,
        "PublishDate": "1404/02/18",
        "Title": "راهنمای رزرو هتل",
        "Price": 2213000
      }
    ]
  }
}
curl
curl -X POST https://panel.seosignal.net/openapi/v1/reportage-buyer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"alibaba.ir","report_type":"cost_analysis","date_range":"last_365"}'
200 OK
{
  "ok": true,
  "report_type": "cost_analysis",
  "limit": 250,
  "usage": 20,
  "data": {
    "LastYearCost": {
      "DateList": ["1404 مهر", "1404 آبان"],
      "Prices": [4200000, 3100000]
    },
    "LastMonthCost": {
      "DateList": ["1404/08/01", "1404/08/02"]
    }
  }
}

لیست پروژه‌های ردیاب رتبه

فهرست پروژه‌های ردیاب رتبه کاربر، به‌همراه تعداد دامنه/کلمه کلیدی هر پروژه و سقف پلن.

POST /openapi/v1/ranktracker-projects ∞ بدون سقف روزانه
ⓘ

چون داده ردیاب رتبه متعلق به خودِ حساب شماست، هر چهار endpoint ردیاب رتبه مشمول سقف روزانه OpenAPI نیستند. همچنین، برخلاف سایر endpointها، فیلد Id هر پروژه در خروجی حذف نمی‌شود — برای فراخوانی جزئیات پروژه لازم است.

پارامترهای بدنه

این endpoint بدون پارامتر است — بدنه درخواست می‌تواند خالی ({}) باشد.

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

curl 
curl -X POST https://panel.seosignal.net/openapi/v1/ranktracker-projects \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

نمونه پاسخ

200 OK
{
  "ok": true,
  "data": {
    "List": [
      {
        "Id": 37113,
        "Name": "پروژه دیوار — اصفهان",
        "CheckDate": "1405/07/06",
        "DomainCount": 1,
        "MainDomain": "divar.ir",
        "KeywordCount": 3,
        "IsActive": true,
        "IsOwner": true
      }
    ],
    "ProjectCount": 8,
    "ActiveCount": 7,
    "KeywordLimit": 1000,
    "KeywordCount": 79,
    "DomainLimit": 30,
    "DomainCount": 13
  }
}

جزئیات پروژه ردیاب رتبه

دامنه اصلی، کلمات کلیدی، دامنه‌های رقیب، شهر بررسی رتبه و شناسه‌های گزارش‌گیری (mobile_id/desktop_id) یک پروژه — گام میانی لازم قبل از فراخوانی گزارش دامنه اصلی.

POST /openapi/v1/ranktracker-project-detail ∞ بدون سقف روزانه
⚠

project_id باید متعلق به همان حسابی باشد که کلید API از آن ساخته شده؛ در غیر این‌صورت خطای REQUEST_FAILED برمی‌گردد.

پارامترهای بدنه

کلیدنوعتوضیح
project_id
الزامی		intشناسه پروژه (از پاسخ لیست پروژه‌ها)

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

curl 
curl -X POST https://panel.seosignal.net/openapi/v1/ranktracker-project-detail \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":37113}'

نمونه پاسخ

200 OK
{
  "ok": true,
  "data": {
    "name": "پروژه دیوار — اصفهان",
    "main_domain": "divar.ir",
    "is_active": true,
    "keywords": ["آپارتمان", "خرید آپارتمان", "اجاره آپارتمان"],
    "competitor_domains": [],
    "location": "اصفهان",
    "country_code": "IR",
    "mobile_id": 87,
    "desktop_id": 88
  }
}

وضعیت تغییر رتبه‌ها

وضعیت رتبه کلمات کلیدی یک دامنه پروژه (اصلی یا رقیب) در یک بازه زمانی — رتبه، تغییر رتبه نسبت به ابتدای بازه، بهترین رتبه و حجم جستجو.

POST /openapi/v1/ranktracker-rank-status ∞ بدون سقف روزانه
⚠

project_id باید متعلق به همان حسابی باشد که کلید API از آن ساخته شده و device_id باید یکی از mobile_id/desktop_id همان پروژه (از پاسخ جزئیات پروژه) باشد؛ در غیر این‌صورت خطای REQUEST_FAILED برمی‌گردد.

پارامترهای بدنه

کلیدنوعتوضیح
project_id
الزامی		intشناسه پروژه (از پاسخ لیست پروژه‌ها)
device_id
الزامی		intmobile_id یا desktop_id همان پروژه (از پاسخ جزئیات پروژه)
domain
اختیاری		stringدامنه هدف — پیش‌فرض main_domain؛ یا یکی از competitor_domains همان پروژه (از پاسخ جزئیات پروژه)
start_date
اختیاری		stringتاریخ شروع بازه، قالب YYYY-MM-DD — پیش‌فرض دیروز
end_date
اختیاری		stringتاریخ پایان بازه، قالب YYYY-MM-DD — پیش‌فرض امروز (حداکثر بازه ۹۰ روز)
ⓘ

اگر start_date/end_date ارسال نشوند، بازه پیش‌فرض «دیروز تا امروز» است (برای گرفتن وضعیت لحظه‌ای/روزانه). برای روند بلندمدت‌تر، هر دو تاریخ را صریح ارسال کنید (حداکثر ۹۰ روز). ترتیب فراخوانی معمول: ابتدا لیست پروژه‌ها برای گرفتن project_id، سپس جزئیات پروژه برای گرفتن mobile_id/desktop_id، و در نهایت این endpoint با یکی از آن دو مقدار به‌عنوان device_id.

نمونه درخواست و پاسخ

curl
curl -X POST https://panel.seosignal.net/openapi/v1/ranktracker-rank-status \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":37113,"device_id":87}'
200 OK
{
  "ok": true,
  "data": {
    "domain": "divar.ir",
    "device_id": 87,
    "is_main_domain": true,
    "date_range": ["2026-09-28", "2026-09-29"],
    "avg_rank_series": [1, 1.33],
    "visibility_series": [100, 100],
    "rank_distribution": { "رتبه ۱": 2, "رتبه ۲ تا ۳": 1, ... },
    "rank_change_distribution": { "بدون تغییر": 2, "رشد کرده": 0, "افت کرده": 1 },
    "keywords": [
      {
        "keyword": "آپارتمان",
        "rank": 2,
        "rank_change": 1,
        "avg_rank": 1.5,
        "best_rank": 1,
        "best_rank_date": "2026-09-28",
        "search_volume": 22000,
        "target_url": null,
        "tags": null,
        "check_datetime": "1405/07/07"
      }
    ]
  }
}
curl
curl -X POST https://panel.seosignal.net/openapi/v1/ranktracker-rank-status \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":37113,"device_id":87,"start_date":"2026-08-30","end_date":"2026-09-29"}'
200 OK
{
  "ok": true,
  "data": {
    "domain": "divar.ir",
    "device_id": 87,
    "is_main_domain": true,
    "date_range": ["2026-08-30", "...", "2026-09-29"],
    "avg_rank_series": [ ... ],
    "visibility_series": [ ... ],
    "rank_distribution": { ... },
    "rank_change_distribution": { ... },
    "keywords": [ ... ]
  }
}

وقتی domain یکی از competitor_domains پروژه باشد، همان گزارش برای دامنه رقیب برمی‌گردد و is_main_domain برابر false است.

curl
curl -X POST https://panel.seosignal.net/openapi/v1/ranktracker-rank-status \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":472,"device_id":1,"domain":"torob.com"}'
200 OK
{
  "ok": true,
  "data": {
    "domain": "torob.com",
    "device_id": 1,
    "is_main_domain": false,
    "date_range": ["2026-09-28", "2026-09-29"],
    "avg_rank_series": [32.2, 32],
    "visibility_series": [70, 70],
    "keywords": [ ... ]
  }
}

تاریخچه رتبه کلمات کلیدی

رتبه روزبه‌روز هر کلمه کلیدی یک دامنه پروژه (اصلی یا رقیب) در یک بازه زمانی — برخلاف «وضعیت تغییر رتبه‌ها» که فقط آخرین وضعیت را می‌دهد، اینجا رتبه هر روزِ بازه به‌صورت جداگانه برمی‌گردد.

POST /openapi/v1/ranktracker-rank-history ∞ بدون سقف روزانه
⚠

project_id باید متعلق به همان حسابی باشد که کلید API از آن ساخته شده و device_id باید یکی از mobile_id/desktop_id همان پروژه (از پاسخ جزئیات پروژه) باشد؛ در غیر این‌صورت خطای REQUEST_FAILED برمی‌گردد.

پارامترهای بدنه

کلیدنوعتوضیح
project_id
الزامی		intشناسه پروژه (از پاسخ لیست پروژه‌ها)
device_id
الزامی		intmobile_id یا desktop_id همان پروژه (از پاسخ جزئیات پروژه)
domain
اختیاری		stringدامنه هدف — پیش‌فرض main_domain؛ یا یکی از competitor_domains همان پروژه (از پاسخ جزئیات پروژه)
start_date
اختیاری		stringتاریخ شروع بازه، قالب YYYY-MM-DD — پیش‌فرض دیروز
end_date
اختیاری		stringتاریخ پایان بازه، قالب YYYY-MM-DD — پیش‌فرض امروز (حداکثر بازه ۹۰ روز)

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

curl 
curl -X POST https://panel.seosignal.net/openapi/v1/ranktracker-rank-history \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":37113,"device_id":87,"start_date":"2026-09-22","end_date":"2026-09-29"}'

نمونه پاسخ

200 OK
{
  "ok": true,
  "data": {
    "domain": "divar.ir",
    "device_id": 87,
    "date_range": ["2026-09-28", "2026-09-29"],
    "avg_rank_series": [1, 1.33],
    "visibility_series": [100, 100],
    "keywords": [
      {
        "keyword": "آپارتمان",
        "search_volume": 22000,
        "target_url": null,
        "tags": null,
        "start_rank": 1,
        "end_rank": 2,
        "rank_change": 1,
        "avg_rank": 1.5,
        "best_rank": 1,
        "best_rank_date": "2026-09-28",
        "history": [
          { "date": "2026-09-28", "rank": 1 },
          { "date": "2026-09-29", "rank": 2 }
        ]
      }
    ]
  }
}