مستندات فنی API کانال‌جو

مقدمه و آدرس پایه

وب‌سایت کانال‌جو (canaljoo.ir) بستری جهت معرفی، بررسی و رتبه‌بندی کانال‌های فعال در پیام‌رسان‌ها و پلتفرم‌های داخلی از جمله روبیکا، بله و ایتا است. از طریق این API می‌توانید به اطلاعات آماری، رتبه‌بندی‌ها و روند رشد کانال‌ها دسترسی داشته باشید.

احراز هویت (Authentication)

برای استفاده از API کانال‌جو، نیاز به توکن اختصاصی (API Token) دارید. جهت دریافت توکن، باید به حساب کاربری خود در وب‌سایت کانال‌جو مراجعه کرده و از بخش تنظیمات/کلیدهای API، اقدام به دریافت توکن نمایید.

توکن دریافتی باید در هدر تمام درخواست‌ها به صورت Bearer Token ارسال شود:

Authorization: Bearer YOUR_API_TOKEN

دریافت اطلاعات یک کانال خاص

جهت دریافت جزئیات، آمار رشد و رتبه‌بندی یک کانال مشخص، درخواست خود را به متد زیر ارسال کنید:

پارامترهای مسیر (Path Parameters):

ساختار پاسخ (Response Schema)

پاسخ‌های دریافتی از API در قالب فرمت استاندارد JSON ارائه می‌شوند. نمونه پاسخ موفق برای یک کانال به شرح زیر است:

{
  "status": "success",
  "data": {
    "title": "کانال آموزشی کانال‌جو",
    "description": "توضیحات رسمی مربوط به کانال و محورهای فعالیت آن",
    "avatar_url": "https://canaljoo.ir/uploads/avatars/channel_sample.png",
    "category": "آموزش",
    "platform": "eitaa",
    "members_count": 12500,
    "is_verified": true,
    "created_at": "2023-05-12T14:30:00Z",
    "updated_at": "2024-11-20T08:15:00Z",
    "tags": ["آموزش", "برنامه‌نویسی", "فناوری"],
    "location": {
      "province": "تهران",
      "city": "تهران"
    },
    "rankings": {
      "rank_global": 124,
      "rank_in_platform": 45,
      "rank_in_category": 12,
      "rank_in_province": 82,
      "rank_in_city": 70
    },
    "growth_stats": {
      "growth_24h": 150,
      "growth_7d": 850,
      "growth_30d": -200
    },
    "members_history_30d": [
      12700, 12680, 12650, 12600, 12580, 12550, 12500
    ]
  }
}

توضیحات فیلدهای پاسخ:

کدهای خطا (Error Codes)

در صورت بروز خطا در پردازش درخواست، پاسخ با کدهای وضعیت استاندارد HTTP و ساختار خطای زیر ارسال می‌شود:

{
  "status": "error",
  "error": {
    "code": 401,
    "message": "Token is invalid or expired."
  }
}