API ডকুমেন্টেশন

Telegram চ্যানেল সার্চ ও Export করার জন্য REST API v1। JSON, cursor পেজিনেশন, UI ও Export-এর মতোই একই ফিল্টার স্কিমা। মেশিন-রিডেবল স্কিমা হলো ব্যাকএন্ডের OpenAPI (/openapi.json)।

বেস URL: https://tgmarket.io/api. নিচের সব পাথ এর সাপেক্ষে।

MCP দিয়ে AI অ্যাসিস্ট্যান্ট যুক্ত করুন →

অথেন্টিকেশন

কী তৈরি করুন ড্যাশবোর্ড → API keys -এ (পেইড প্ল্যান)। কী-এর ফরম্যাট: mk_live_<prefix>_<secret>, শুধু একবারই দেখানো হয়। এটি হেডারে পাঠান:

Authorization: Bearer mk_live_ab12cd34_xxxxxxxxxxxxxxxx
# অথবা
X-API-Key: mk_live_ab12cd34_xxxxxxxxxxxxxxxx

Scope: read (ডিফল্ট) এবং export — POST /v1/exports, POST/PATCH/DELETE /v1/webhooks-এর জন্য। সর্বোচ্চ দুটি সক্রিয় কী, যাতে ডাউনটাইম ছাড়াই কী বদলাতে পারেন।

বিলিং

আপনি কলের জন্য নয়, ফেরত পাওয়া ডেটার জন্য পেমেন্ট করেন। সবকিছু ক্রেডিটে চার্জ হয়: 1 ক্রেডিট = $0.001।

  • প্রতিটি পেইড রিকোয়েস্ট — 1 ক্রেডিট (প্রতি 1,000 রিকোয়েস্টে $1)।
  • প্রতিটি চ্যানেল রো — ফিল্ড-সেটের রেট অনুযায়ী: Base 0.5 ক্রেডিট, +Metrics 1.5, +Ads 2, History 3।
  • প্রতিটি পোস্ট — 0.5 ক্রেডিট।
  • এই কী দিয়ে গত 30 দিনে যে চ্যানেলের জন্য আগেই পেমেন্ট হয়েছে, সেটি ফ্রি দেওয়া হয়।
  • /count ও ফেসেট — শুধু রিকোয়েস্ট ফি।

চার্জ হওয়া পরিমাণ ফেরত আসে X-Credits-Charged হেডারে। ব্যালেন্স ও ব্যবহার — GET /v1/usage। Export-এর দাম — দেখুন প্রাইসিং.

এন্ডপয়েন্ট

মেথডপাথবিবরণখরচ
GET/v1/categoriesক্যাটাগরি ট্রিফ্রি
GET/v1/languagesচ্যানেল সংখ্যাসহ ভাষাফ্রি
GET/v1/geoচ্যানেল সংখ্যাসহ দেশ; ?country= — সেই দেশের অঞ্চল (regions ফিল্টারের কোড)ফ্রি
GET/v1/usageব্যালেন্স, দৈনিক ব্যবহার, লিমিটফ্রি
POST/v1/channels/searchফিল্টার + q, cursor, প্রতি পেজে সর্বোচ্চ 100রিকোয়েস্ট + রো সমূহ
POST/v1/channels/countগণনা ও ফেসেটরিকোয়েস্ট
GET/v1/channels/{id|username}চ্যানেল কার্ড (?fields=base,metrics,ads; reach — দৈনিক রিচ)রিকোয়েস্ট + রো
GET/v1/channels/{id}/historyদৈনিক সাবস্ক্রাইবার, মেট্রিক্স ও দৈনিক রিচ (?days=)রিকোয়েস্ট + History
GET/v1/channels/{id}/postsসাম্প্রতিক পোস্ট (?limit= সর্বোচ্চ 100)রিকোয়েস্ট + পোস্ট
GET/v1/channels/{id}/referencesকারা উল্লেখ করেছে / কাদের উল্লেখ করেরিকোয়েস্ট + রো সমূহ
GET/v1/advertisers৩০ দিনে চ্যানেলের সংখ্যা অনুযায়ী বিজ্ঞাপনদাতা (group, lang, country, q)রিকোয়েস্ট
GET/v1/advertisers/{key}বিজ্ঞাপনদাতা ও তার চ্যানেল (limit, offset)রিকোয়েস্ট + রো সমূহ
POST/v1/posts/searchপোস্টে ফুল-টেক্সট সার্চরিকোয়েস্ট + পোস্ট
POST/v1/posts/trendশব্দের উল্লেখের প্রবণতা: প্রতিদিন পোস্ট, চ্যানেল ও ভিউ (group=day|week)রিকোয়েস্ট + প্রতি বিন্দু 0.01
POST/v1/exportsঅ্যাসিঙ্ক Export (export scope)Export-এর দাম
POST/v1/exports/quoteঅর্ডারের আগে এক্সপোর্টের দাম: সারি, বিনামূল্যের সারি, ছাড়রিকোয়েস্ট
GET/v1/exports/{id}স্ট্যাটাস ও ডাউনলোড লিংকফ্রি
GET/v1/feedsEnterprise: দৈনিক ফিডের দিনগুলো (নতুন, পরিবর্তিত ও মুছে ফেলা চ্যানেল, Parquet)ফ্রি
GET/v1/feeds/{date}Enterprise: দিনের ফাইলের সাইন করা লিংক (export scope)দিনের সারি চুক্তির হারে, একবার

ফিল্টার (ChannelQuery)

query অবজেক্ট /channels/search, /channels/count ও /exports-এর জন্য একই। খালি ফিল্ড বাদ দিন।

qstringটেক্সট: শিরোনাম, username, বিবরণ, পোস্ট
category_ids / exclude_category_idsint[]ক্যাটাগরি (বিভাগ বা সাবক্যাটাগরি)
channel_idsint[]নির্দিষ্ট চ্যানেল
languages / exclude_languagesstring[]ভাষার কোড: ru, en, uk…
countries / regions / exclude_countriesstring[]ভূগোল: ISO দেশ কোড (IN, US) ও /v1/geo থেকে অঞ্চল "US:Texas"; অঞ্চল শুধু নিজের দেশকে সীমিত করে
kindall | channel | groupধরন
subscribers_min / subscribers_maxintসাবস্ক্রাইবার
avg_views_min, reach_24h_minnumberভিউ ও 24 ঘণ্টার রিচ
er_min, err_24h_minnumberER / ERR, %
growth_7d_min, growth_30d_min, growth_pct_30d_minnumberগ্রোথ
posts_30d_min, last_post_afterint, dateঅ্যাক্টিভিটি
chat_mau_minintসক্রিয় কমেন্টকারী: ডিসকাশন চ্যাটে ইউনিক লেখক, 30 দিন
daily_reach_minintদৈনিক রিচ (আনুমানিক): দিনের পোস্টগুলোর 24 ঘণ্টার ভিউয়ের যোগফল; 30 দিনের গড়
reach_48h_minint৪৮ ঘণ্টায় পোস্ট রিচ: প্রকাশের ৪৮ ঘণ্টা পরে পোস্টের গড় ভিউ, ৩০ দিনে
premium_share_min0..100আলোচনার লেখকদের মধ্যে Telegram Premium অংশ, %, অনুমান (৫০+ লেখক)
female_share_min0..100চেনা নামের লেখকদের মধ্যে নারীর অংশ, %, অনুমান — সর্বনিম্ন
female_share_max0..100একই — সর্বোচ্চ
created_after / created_beforedateতৈরির তারিখ
has_ads_contact, ad_share_maxbool, 0..1বিজ্ঞাপন
fraud_max0..1ফ্রড স্কোরের সীমা
verified_only, exclude_scamboolফ্ল্যাগ (ডিফল্টভাবে exclude_scam=true)
sort, orderstringসর্টের ফিল্ড; order — desc|asc
relevance, subscribers, growth_7d, growth_30d, growth_pct_30d, reach_24h, avg_views, er, citation_index, created_at, last_post_at, chat_mau, daily_reach, reach_48h, premium_share

উদাহরণ

চ্যানেল সার্চ

curl -X POST https://tgmarket.io/api/v1/channels/search \
  -H "Authorization: Bearer $MK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {"q": "শেয়ার বাজার", "languages": ["bn"], "subscribers_min": 5000, "sort": "growth_30d"},
    "fields": ["base", "metrics"],
    "limit": 100
  }'

রেসপন্স:

{
  "items": [{"id": 2365318039, "username": "GPTronhub", "title": "…", "subscribers": 169432, "er": 0.16, …}],
  "total": 605,
  "next_cursor": "eyJoIjoi…"   // পরের রিকোয়েস্টে cursor হিসেবে পাঠান
}

শুধু গণনা

curl -X POST https://tgmarket.io/api/v1/channels/count -H "Authorization: Bearer $MK_KEY" \
  -H "Content-Type: application/json" -d '{"query": {"category_ids": [21]}}'

কার্ড ও হিস্ট্রি

curl "https://tgmarket.io/api/v1/channels/durov?fields=base,metrics" -H "Authorization: Bearer $MK_KEY"
curl "https://tgmarket.io/api/v1/channels/1006503122/history?days=90" -H "Authorization: Bearer $MK_KEY"

Export

curl -X POST https://tgmarket.io/api/v1/exports -H "Authorization: Bearer $MK_KEY" -H "Content-Type: application/json" \
  -d '{"query": {"q": "ক্রিপ্টো"}, "fields": ["base","metrics"], "format": "csv", "row_limit": 20000}'
# → {"export_id": "…", "rows": 20000, "price_credits": 32000, "status": "queued"}

curl https://tgmarket.io/api/v1/exports/<export_id> -H "Authorization: Bearer $MK_KEY"
# → {"status": "done", "progress": 100, "download_url": "https://…", …}

রেট লিমিট

  • Premium — প্রতি সেকেন্ডে 1টি রিকোয়েস্ট, Business — 3, Super — 10, Enterprise — চুক্তি অনুযায়ী।
  • প্রতিটি রেসপন্সে থাকে X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
  • একটি কোয়েরিতে 10,000-এর বেশি রেজাল্টের জন্য — /v1/exports ব্যবহার করুন।
  • প্রতি কী-তে ইউনিক চ্যানেলের একটি কঠোর দৈনিক সীমা আছে; তা ছাড়ালে ম্যানুয়াল রিভিউ পর্যন্ত কী ফ্রিজ হয়ে যায়।

এরর

সব এরর একই ফরম্যাটে আসে:

{"error": {"code": "payment_required", "message": "…"}}
  • 401 invalid_api_key — অবৈধ বা বাতিল করা কী
  • 402 payment_required / 402 insufficient_funds — ব্যালেন্স শেষ, ড্যাশবোর্ডে টপ-আপ করুন (বডিতে need/have)
  • 403 api_not_in_plan, 403 scope_required, 403 key_frozen, 403 ip_not_allowed
  • 429 rate_limited — RPS ছাড়িয়ে গেছে; কত সেকেন্ড অপেক্ষা করতে হবে তা দেখুন Retry-After
  • 400 too_deep, 400 bad_cursor, 422 — অবৈধ প্যারামিটার

Webhooks

নজরে রাখা চ্যানেলের নতুন পোস্ট সরাসরি আপনার সার্ভারে: প্রতি পোস্টে JSON body সহ একটি HTTP POST, চাইলে কীওয়ার্ড ফিল্টারসহ।

বিলম্ব নিয়ে স্পষ্ট কথা: আমাদের crawler প্রতিটি চ্যানেল ৩–১৪ দিনে একবার দেখে, তাই পোস্ট ব্যাচে আসে, প্রায়ই প্রকাশের কয়েক দিন পরে। আমাদের কাছে আসার পর পোস্ট প্রায় এক মিনিটে পৌঁছায়; event-এ আসল তারিখ ও delay_seconds থাকে। এটি real-time ফিড নয়।

Endpoint তৈরি করুন ড্যাশবোর্ড → Webhooks-এ বা নিচের API দিয়ে, তারপর subscriptions যোগ করুন: চ্যানেলের তালিকা (id বা @username) ও ঐচ্ছিক কীওয়ার্ড — পোস্টে এর যেকোনোটি থাকলে তা পৌঁছানো হয় (case-insensitive)।

  • 2xx উত্তরে পৌঁছানো প্রতিটি পোস্টের দাম 0.5 ক্রেডিট, key (বা সংস্থার) ব্যালেন্স থেকে কাটা হয়। পরিচালনা, টেস্ট ping ও ব্যর্থ চেষ্টা বিনামূল্যে। ব্যালেন্স শূন্য হলে ডেলিভারি হারায় না, ৭২ ঘণ্টা পর্যন্ত অপেক্ষা করে।
  • সব subscription মিলিয়ে নজরে থাকা চ্যানেল: Premium — ১০০, Business — ৩০০, Super — ১,০০০। সর্বোচ্চ ৫টি endpoint, প্রতি endpoint-এ ৫০টি subscription।
GET/v1/webhooksSubscriptions সহ endpoints; প্ল্যানের সীমা ও ৩০ দিনের ব্যবহার
POST/v1/webhooksEndpoint তৈরি {name, url}; signing secret একবারই ফেরত আসে
GET · PATCH · DELETE/v1/webhooks/{id}Endpoint দেখা, বদলানো {name, url, active} বা মোছা
POST/v1/webhooks/{id}/rotate-secretনতুন signing secret (পুরোনোটি সঙ্গে সঙ্গে বাতিল)
POST/v1/webhooks/{id}/testএখনই ping event পাঠান (বিনামূল্যে)
POST/v1/webhooks/{id}/subscriptionsSubscription যোগ {channels, keywords?, name?}
PATCH · DELETE/v1/webhooks/{id}/subscriptions/{sub_id}Subscription বদলান বা মুছুন
GET/v1/webhooks/{id}/deliveries[/{delivery_id}]ডেলিভারি লগ, নতুনগুলো আগে (?status=, ?before_id=)
POST/v1/webhooks/{id}/deliveries/{delivery_id}/retryব্যর্থ বা মেয়াদোত্তীর্ণ ডেলিভারি আবার সারিতে দিন
curl -X POST https://tgmarket.io/api/v1/webhooks -H "Authorization: Bearer $MK_KEY" -H "Content-Type: application/json" \
  -d '{"name": "crm", "url": "https://example.com/hooks/tgmarket"}'
# → {"id": "…", "secret": "whsec_…", …}

curl -X POST https://tgmarket.io/api/v1/webhooks/<id>/subscriptions -H "Authorization: Bearer $MK_KEY" \
  -H "Content-Type: application/json" -d '{"channels": ["@durov", 1006503122], "keywords": ["bitcoin"]}'

Event body

{
  "id": "evt_3f2a…",                      // = X-TGMarket-Idempotency-Key
  "type": "post.created",
  "created_at": "2026-10-05T12:00:41+00:00",
  "endpoint_id": "…",
  "subscription_ids": ["…"],
  "matched_keywords": ["bitcoin"],
  "channel": {"id": 1006503122, "username": "durov", "title": "Durov's Channel"},
  "post": {
    "id": 98765432, "message_id": 321, "date": "2026-09-30T08:15:00+00:00",
    "url": "https://t.me/durov/321", "text": "…", "views": 1200000, "forwards": 3100,
    "replies": 0, "reactions": 45000, "has_media": true, "media_type": "photo",
    "forward_from_channel_id": null, "reply_to_message_id": null, "mentioned_usernames": []
  },
  "collected_at": "2026-10-05T12:00:20+00:00",
  "delay_seconds": 445520
}

Signature

প্রতিটি request-এ headers থাকে: X-TGMarket-Event (post.created বা ping), X-TGMarket-Delivery, X-TGMarket-Idempotency-Key, X-TGMarket-Timestamp এবং X-TGMarket-Signature: v1=<hex>, যেখানে hex = HMAC-SHA256(secret, timestamp + "." + raw body)। যে request-এর timestamp ৫ মিনিটের বেশি আলাদা, তা প্রত্যাখ্যান করুন।

Signature যাচাই (Python)

import hashlib, hmac, time

def verify(secret: str, headers, raw_body: bytes) -> bool:
    ts = int(headers["X-TGMarket-Timestamp"])
    if abs(time.time() - ts) > 300:
        return False
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"v1={mac}", headers["X-TGMarket-Signature"])
  • পুনরায় চেষ্টা: যেকোনো non-2xx উত্তর, timeout (10 s) বা connection error exponential backoff-এ আবার চেষ্টা হয় — ১, ২, ৪… মিনিট, সর্বোচ্চ ৬ ঘণ্টা ব্যবধান, ১০টি চেষ্টা। Redirect অনুসরণ করা হয় না। ব্যর্থতা ২৪ ঘণ্টা ধরে চলতে থাকলে (পরপর অন্তত ২০টি) endpoint বন্ধ হয় এবং owner ইমেল পান; PATCH active=true দিয়ে চালু করুন, অপেক্ষমাণ ডেলিভারি আবার চলবে।
  • X-TGMarket-Idempotency-Key (= event id) দিয়ে ডুপ্লিকেট বাদ দিন: একটি endpoint-এ একটি পোস্টের সব চেষ্টায় এটি একই থাকে, এবং কোনো পোস্ট একই endpoint-এর জন্য দুবার সারিতে আসে না।
  • URL-এর শর্ত: শুধু https, পাবলিক domain বা IP; private, loopback ও link-local ঠিকানা (পাঠানোর সময় DNS-এ পাওয়া ঠিকানাও) প্রত্যাখ্যাত; URL-এ login/password নয়। দ্রুত 2xx দিন এবং async-ভাবে প্রক্রিয়া করুন।