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_xxxxxxxxxxxxxxxxScope: 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/feeds | Enterprise: দৈনিক ফিডের দিনগুলো (নতুন, পরিবর্তিত ও মুছে ফেলা চ্যানেল, Parquet) | ফ্রি |
| GET | /v1/feeds/{date} | Enterprise: দিনের ফাইলের সাইন করা লিংক (export scope) | দিনের সারি চুক্তির হারে, একবার |
ফিল্টার (ChannelQuery)
query অবজেক্ট /channels/search, /channels/count ও /exports-এর জন্য একই। খালি ফিল্ড বাদ দিন।
| q | string | টেক্সট: শিরোনাম, username, বিবরণ, পোস্ট |
| category_ids / exclude_category_ids | int[] | ক্যাটাগরি (বিভাগ বা সাবক্যাটাগরি) |
| channel_ids | int[] | নির্দিষ্ট চ্যানেল |
| languages / exclude_languages | string[] | ভাষার কোড: ru, en, uk… |
| countries / regions / exclude_countries | string[] | ভূগোল: ISO দেশ কোড (IN, US) ও /v1/geo থেকে অঞ্চল "US:Texas"; অঞ্চল শুধু নিজের দেশকে সীমিত করে |
| kind | all | channel | group | ধরন |
| subscribers_min / subscribers_max | int | সাবস্ক্রাইবার |
| avg_views_min, reach_24h_min | number | ভিউ ও 24 ঘণ্টার রিচ |
| er_min, err_24h_min | number | ER / ERR, % |
| growth_7d_min, growth_30d_min, growth_pct_30d_min | number | গ্রোথ |
| posts_30d_min, last_post_after | int, date | অ্যাক্টিভিটি |
| chat_mau_min | int | সক্রিয় কমেন্টকারী: ডিসকাশন চ্যাটে ইউনিক লেখক, 30 দিন |
| daily_reach_min | int | দৈনিক রিচ (আনুমানিক): দিনের পোস্টগুলোর 24 ঘণ্টার ভিউয়ের যোগফল; 30 দিনের গড় |
| reach_48h_min | int | ৪৮ ঘণ্টায় পোস্ট রিচ: প্রকাশের ৪৮ ঘণ্টা পরে পোস্টের গড় ভিউ, ৩০ দিনে |
| premium_share_min | 0..100 | আলোচনার লেখকদের মধ্যে Telegram Premium অংশ, %, অনুমান (৫০+ লেখক) |
| female_share_min | 0..100 | চেনা নামের লেখকদের মধ্যে নারীর অংশ, %, অনুমান — সর্বনিম্ন |
| female_share_max | 0..100 | একই — সর্বোচ্চ |
| created_after / created_before | date | তৈরির তারিখ |
| has_ads_contact, ad_share_max | bool, 0..1 | বিজ্ঞাপন |
| fraud_max | 0..1 | ফ্রড স্কোরের সীমা |
| verified_only, exclude_scam | bool | ফ্ল্যাগ (ডিফল্টভাবে exclude_scam=true) |
| sort, order | string | সর্টের ফিল্ড; 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_allowed429 rate_limited— RPS ছাড়িয়ে গেছে; কত সেকেন্ড অপেক্ষা করতে হবে তা দেখুনRetry-After400 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/webhooks | Subscriptions সহ endpoints; প্ল্যানের সীমা ও ৩০ দিনের ব্যবহার |
| POST | /v1/webhooks | Endpoint তৈরি {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}/subscriptions | Subscription যোগ {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-ভাবে প্রক্রিয়া করুন।