API डॉक्यूमेंटेशन
Telegram चैनलों को खोजने और Export करने के लिए REST API v1। JSON, cursor पेजिनेशन, और वही फ़िल्टर स्कीमा जो UI और Export में है। मशीन-रीडेबल स्कीमा बैकएंड का OpenAPI (/openapi.json) है।
बेस URL: https://tgmarket.io/api. नीचे दिए गए सभी पाथ इसी के सापेक्ष हैं।
ऑथेंटिकेशन
API key यहाँ बनाएँ: डैशबोर्ड → API keys (पेड प्लान)। Key का फ़ॉर्मेट: mk_live_<prefix>_<secret>, यह सिर्फ़ एक बार दिखाई जाती है। इसे हेडर में भेजें:
Authorization: Bearer mk_live_ab12cd34_xxxxxxxxxxxxxxxx
# या
X-API-Key: mk_live_ab12cd34_xxxxxxxxxxxxxxxxScopes: read (डिफ़ॉल्ट) और export — POST /v1/exports, POST/PATCH/DELETE /v1/webhooks के लिए। अधिकतम दो सक्रिय keys, ताकि आप बिना डाउनटाइम के key बदल सकें।
बिलिंग
आप लौटाए गए डेटा के लिए भुगतान करते हैं, कॉल के लिए नहीं। सब कुछ क्रेडिट में चार्ज होता है: 1 क्रेडिट = $0.001।
- हर पेड रिक्वेस्ट — 1 क्रेडिट ($1 प्रति 1,000 रिक्वेस्ट)।
- हर चैनल रो — फ़ील्ड-सेट की दर से: Base 0.5 क्रेडिट, +Metrics 1.5, +Ads 2, History 3।
- हर पोस्ट — 0.5 क्रेडिट।
- जिस चैनल के लिए इस key से 30 दिनों के भीतर भुगतान हो चुका है, वह मुफ़्त लौटाया जाता है।
- /count और facets — सिर्फ़ रिक्वेस्ट शुल्क।
कितना चार्ज हुआ, यह X-Credits-Charged हेडर में लौटाया जाता है। बैलेंस और उपयोग — GET /v1/usage। Export की कीमतें — देखें प्लान और कीमतें.
Endpoints
| मेथड | पाथ | विवरण | कीमत |
|---|---|---|---|
| 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 | गिनती और facets | रिक्वेस्ट |
| 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 | 30 दिनों में चैनलों की संख्या के अनुसार विज्ञापनदाता (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 | Async Export (export scope) | Export की कीमत |
| POST | /v1/exports/quote | ऑर्डर से पहले Export की कीमत: पंक्तियाँ, मुफ़्त पंक्तियाँ, छूट | रिक्वेस्ट |
| 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 | 48 घंटे पर पोस्ट रीच: प्रकाशन के 48 घंटे बाद पोस्ट के औसत व्यूज़, 30 दिनों में |
| premium_share_min | 0..100 | चर्चा लेखकों में Telegram Premium हिस्सा, %, अनुमान (50+ लेखक) |
| 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": ["hi"], "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. - एक query में 10,000 से ज़्यादा नतीजों के लिए /v1/exports का इस्तेमाल करें।
- हर key के लिए यूनिक चैनलों की एक सख़्त दैनिक सीमा है; इसे पार करने पर key मैनुअल जाँच तक फ़्रीज़ हो जाती है।
एरर
सभी एरर का फ़ॉर्मेट एक जैसा है:
{"error": {"code": "payment_required", "message": "…"}}401 invalid_api_key— अमान्य या रद्द की गई key402 payment_required/402 insufficient_funds— बैलेंस खत्म हो गया, डैशबोर्ड में टॉप-अप करें (body में 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 हर चैनल को 3–14 दिन में एक बार देखता है, इसलिए पोस्ट बैच में आती हैं, अक्सर प्रकाशन के कई दिन बाद। हमारे पास आने के बाद पोस्ट लगभग एक मिनट में डिलीवर होती है; event में असली तारीख और delay_seconds होते हैं। यह real-time फ़ीड नहीं है।
Endpoint बनाएँ डैशबोर्ड → Webhooks में या नीचे दिए API से, फिर subscriptions जोड़ें: चैनलों की सूची (id या @username) और वैकल्पिक कीवर्ड — पोस्ट तब डिलीवर होती है जब उसमें इनमें से कोई हो (case-insensitive)।
- 2xx जवाब के साथ डिलीवर हर पोस्ट 0.5 क्रेडिट की है, जो key (या संगठन) के बैलेंस से कटती है। मैनेजमेंट, टेस्ट ping और विफल प्रयास मुफ़्त हैं। बैलेंस शून्य होने पर डिलीवरी गुम नहीं होती, 72 घंटे तक इंतज़ार करती है।
- सभी subscriptions में देखे जा रहे चैनल: Premium — 100, Business — 300, Super — 1,000। अधिकतम 5 endpoints, हर endpoint पर 50 subscriptions।
| GET | /v1/webhooks | Subscriptions के साथ endpoints; प्लान लिमिट और 30 दिन का उपयोग |
| 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)। जिन requests का timestamp 5 मिनट से ज़्यादा अलग हो, उन्हें अस्वीकार करें।
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 से दोहराया जाता है — 1, 2, 4… मिनट, अधिकतम 6 घंटे का अंतर, 10 प्रयास। Redirects फ़ॉलो नहीं होते। अगर विफलताएँ 24 घंटे तक चलती रहें (कम से कम लगातार 20), तो endpoint बंद हो जाता है और owner को ईमेल जाता है; PATCH active=true से चालू करें, बाकी डिलीवरी फिर शुरू होंगी।
- X-TGMarket-Idempotency-Key (= event id) से duplicates हटाएँ: एक endpoint पर एक पोस्ट के हर प्रयास में यह एक जैसा रहता है, और कोई पोस्ट एक endpoint के लिए दो बार कतार में नहीं आती।
- URL की शर्तें: सिर्फ़ https, सार्वजनिक domain या IP; private, loopback और link-local पते (भेजते समय DNS से मिले पते भी) अस्वीकार; URL में login/password नहीं। जल्दी 2xx लौटाएँ और प्रोसेसिंग async करें।