API डॉक्युमेंटेशन
Telegram चॅनेल शोधण्यासाठी आणि Export करण्यासाठी REST API v1. JSON, cursor pagination, UI आणि Exports प्रमाणेच फिल्टर स्कीमा. मशीन-रीडेबल स्कीमा म्हणजे बॅकएंडचा OpenAPI (/openapi.json).
बेस URL: https://tgmarket.io/api. खालील सर्व पाथ याच्या सापेक्ष आहेत.
ऑथेंटिकेशन
की तयार करा: डॅशबोर्ड → API keys (सशुल्क प्लॅन). की फॉरमॅट: 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 साठी. जास्तीत जास्त दोन सक्रिय की, त्यामुळे डाउनटाइमशिवाय की बदलता येते.
बिलिंग
तुम्ही परत मिळालेल्या डेटासाठी पैसे देता, कॉल्ससाठी नाही. सर्व शुल्क क्रेडिट्समध्ये आकारले जाते: 1 क्रेडिट = $0.001.
- प्रत्येक सशुल्क रिक्वेस्ट — 1 क्रेडिट (1,000 रिक्वेस्टसाठी $1).
- प्रत्येक चॅनेल रो — फील्ड-सेटच्या दराने: Base 0.5 क्रेडिट्स, +Metrics 1.5, +Ads 2, History 3.
- प्रत्येक पोस्ट — 0.5 क्रेडिट्स.
- या की ने 30 दिवसांत आधीच पैसे दिलेला चॅनेल मोफत परत केला जातो.
- /count आणि facets — फक्त रिक्वेस्ट शुल्क.
आकारलेली रक्कम X-Credits-Charged हेडरमध्ये परत केली जाते. बॅलन्स आणि वापर — GET /v1/usage. Export च्या किमती — पाहा किंमती.
Endpoints
| Method | पाथ | वर्णन | किंमत |
|---|---|---|---|
| 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": ["mr"], "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 वापरा.
- प्रत्येक की साठी युनिक चॅनेलची कठोर दैनिक मर्यादा आहे; ती ओलांडल्यास मॅन्युअल तपासणी होईपर्यंत की फ्रीझ केली जाते.
एरर्स
सर्व एरर्सचा फॉरमॅट एकच आहे:
{"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 आणि अयशस्वी प्रयत्न मोफत. बॅलन्स शून्य असताना डिलिव्हरी हरवत नाहीत, ७२ तासांपर्यंत थांबतात.
- सर्व subscriptions मिळून पाहिले जाणारे चॅनेल: Premium — १००, Business — ३००, Super — १,०००. जास्तीत जास्त ५ endpoints, प्रत्येकी ५० subscriptions.
| 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). ज्यांचा timestamp ५ मिनिटांपेक्षा जास्त वेगळा आहे त्या requests नाकारा.
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 ने पुन्हा केले जाते — १, २, ४… मिनिटे, जास्तीत जास्त ६ तासांचे अंतर, १० प्रयत्न. Redirects पाळले जात नाहीत. अपयश २४ तास सलग चालू राहिल्यास (किमान सलग २०) 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 प्रक्रिया करा.