API डॉक्युमेंटेशन

Telegram चॅनेल शोधण्यासाठी आणि Export करण्यासाठी REST API v1. JSON, cursor pagination, UI आणि Exports प्रमाणेच फिल्टर स्कीमा. मशीन-रीडेबल स्कीमा म्हणजे बॅकएंडचा 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

Scopes: 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/advertisers30 दिवसांतील चॅनेलच्या संख्येनुसार जाहिरातदार (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/exportsAsync Export (export scope)Export किंमत
POST/v1/exports/quoteऑर्डरपूर्वी Export ची किंमत: ओळी, मोफत ओळी, सवलतीरिक्वेस्ट
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_minint48 तासांनी पोस्ट रीच: प्रकाशनानंतर 48 तासांनी पोस्टचे सरासरी व्ह्यूज, 30 दिवसांत
premium_share_min0..100चर्चा लेखकांमध्ये Telegram Premium वाटा, %, अंदाज (50+ लेखक)
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": ["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_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 आणि अयशस्वी प्रयत्न मोफत. बॅलन्स शून्य असताना डिलिव्हरी हरवत नाहीत, ७२ तासांपर्यंत थांबतात.
  • सर्व subscriptions मिळून पाहिले जाणारे चॅनेल: Premium — १००, Business — ३००, Super — १,०००. जास्तीत जास्त ५ endpoints, प्रत्येकी ५० subscriptions.
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). ज्यांचा 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 प्रक्रिया करा.