API ஆவணங்கள்

Telegram சேனல்களைத் தேடவும் Export செய்யவும் REST API v1. JSON, cursor pagination, UI மற்றும் Exports-இல் உள்ள அதே ஃபில்டர் அமைப்பு. இயந்திரம் படிக்கக்கூடிய schema — backend OpenAPI (/openapi.json).

அடிப்படை URL: https://tgmarket.io/api. கீழே உள்ள அனைத்து paths-உம் இதைச் சார்ந்தவை.

MCP மூலம் AI உதவியாளர்களை இணைக்கவும் →

அங்கீகாரம்

Key-ஐ இங்கே உருவாக்குங்கள்: டாஷ்போர்டு → API keys (கட்டண பிளான்கள்). Key வடிவம்: mk_live_<prefix>_<secret>, ஒருமுறை மட்டுமே காட்டப்படும். அதை header-இல் அனுப்புங்கள்:

Authorization: Bearer mk_live_ab12cd34_xxxxxxxxxxxxxxxx
# அல்லது
X-API-Key: mk_live_ab12cd34_xxxxxxxxxxxxxxxx

Scopes: read (இயல்புநிலை) மற்றும் export — POST /v1/exports, POST/PATCH/DELETE /v1/webhooks-க்கு. அதிகபட்சம் இரண்டு செயலில் உள்ள keys, எனவே சேவை நிறுத்தமின்றி key-ஐ மாற்றலாம்.

கட்டணம்

அழைப்புகளுக்கு அல்ல, திருப்பி அனுப்பப்படும் தரவுக்கே நீங்கள் கட்டணம் செலுத்துகிறீர்கள். அனைத்தும் கிரெடிட்களில் கணக்கிடப்படும்: 1 கிரெடிட் = $0.001.

  • ஒவ்வொரு கட்டண request-க்கும் — 1 கிரெடிட் (1,000 requests-க்கு $1).
  • ஒவ்வொரு சேனல் வரிசைக்கும் — ஃபீல்டு தொகுப்பின் விலையில்: Base 0.5 கிரெடிட், +Metrics 1.5, +Ads 2, History 3.
  • ஒவ்வொரு போஸ்டுக்கும் — 0.5 கிரெடிட்.
  • இந்த key கடந்த 30 நாட்களில் ஏற்கனவே கட்டணம் செலுத்திய சேனல் இலவசமாக வழங்கப்படும்.
  • /count மற்றும் facets — request கட்டணம் மட்டும்.

வசூலிக்கப்பட்ட தொகை X-Credits-Charged header-இல் வழங்கப்படும். இருப்பு மற்றும் பயன்பாடு — GET /v1/usage. Export விலைகள் — பார்க்க: பிளான்கள்.

Endpoints

MethodPathவிளக்கம்விலை
GET/v1/categoriesவகை மரம்இலவசம்
GET/v1/languagesசேனல் எண்ணிக்கையுடன் மொழிகள்இலவசம்
GET/v1/geoசேனல் எண்ணிக்கையுடன் நாடுகள்; ?country= — அந்நாட்டின் பகுதிகள் (regions வடிகட்டிக்கான குறியீடுகள்)இலவசம்
GET/v1/usageஇருப்பு, தினசரி பயன்பாடு, வரம்புகள்இலவசம்
POST/v1/channels/searchஃபில்டர்கள் + q, cursor, ஒரு பக்கத்துக்கு 100 வரைrequest + வரிசைகள்
POST/v1/channels/countஎண்ணிக்கைகள் மற்றும் facetsrequest
GET/v1/channels/{id|username}சேனல் கார்டு (?fields=base,metrics,ads; reach — தினசரி ரீச்)request + வரிசை
GET/v1/channels/{id}/historyதினசரி சப்ஸ்கிரைபர்கள், மெட்ரிக்ஸ் & தினசரி ரீச் (?days=)request + History
GET/v1/channels/{id}/postsசமீபத்திய போஸ்ட்கள் (?limit= 100 வரை)request + போஸ்ட்கள்
GET/v1/channels/{id}/referencesமேற்கோள் காட்டியவை / மேற்கோள் காட்டுபவைrequest + வரிசைகள்
GET/v1/advertisers30 நாட்களில் சேனல்களின் எண்ணிக்கைப்படி விளம்பரதாரர்கள் (group, lang, country, q)request
GET/v1/advertisers/{key}விளம்பரதாரர் மற்றும் அதன் சேனல்கள் (limit, offset)request + வரிசைகள்
POST/v1/posts/searchபோஸ்ட்களில் முழு உரைத் தேடல்request + போஸ்ட்கள்
POST/v1/posts/trendசொல்லின் குறிப்புகள் காலப்போக்கில்: நாளொன்றுக்கு போஸ்ட்கள், சேனல்கள், பார்வைகள் (group=day|week)request + ஒரு புள்ளிக்கு 0.01
POST/v1/exportsAsync Export (export scope)Export விலை
POST/v1/exports/quoteஆர்டருக்கு முன் ஏற்றுமதி விலை: வரிசைகள், இலவச வரிசைகள், தள்ளுபடிகள்request
GET/v1/exports/{id}நிலை மற்றும் பதிவிறக்க இணைப்புஇலவசம்
GET/v1/feedsEnterprise: தினசரி feed நாட்கள் (புதிய, மாற்றப்பட்ட, நீக்கப்பட்ட சேனல்கள், Parquet)இலவசம்
GET/v1/feeds/{date}Enterprise: அன்றைய கோப்புக்கான கையொப்பமிட்ட இணைப்பு (export scope)அன்றைய வரிசைகள் ஒப்பந்த விகிதத்தில், ஒருமுறை

ஃபில்டர்கள் (ChannelQuery)

/channels/search, /channels/count மற்றும் /exports-க்கு query object ஒன்றே. காலியான ஃபீல்டுகளை விட்டுவிடுங்கள்.

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செயலில் உள்ள கமெண்டர்கள்: விவாத chat-இல் தனித்துவமான ஆசிரியர்கள், 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_scamboolflags (இயல்பாக 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": ["ta"], "subscribers_min": 5000, "sort": "growth_30d"},
    "fields": ["base", "metrics"],
    "limit": 100
  }'

Response:

{
  "items": [{"id": 2365318039, "username": "GPTronhub", "title": "…", "subscribers": 169432, "er": 0.16, …}],
  "total": 605,
  "next_cursor": "eyJoIjoi…"   // அடுத்த request-இல் 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 request, Business — 3, Super — 10, Enterprise — ஒப்பந்தப்படி.
  • ஒவ்வொரு response-இலும் இந்த headers உள்ளன: 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 — தவறான அல்லது ரத்து செய்யப்பட்ட key
  • 402 payment_required / 402 insufficient_funds — இருப்பு தீர்ந்துவிட்டது, டாஷ்போர்டில் ரீசார்ஜ் செய்யுங்கள் (body-இல் 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 — தவறான parameters

Webhooks

கண்காணிக்கும் சேனல்களின் புதிய பதிவுகள் நேரடியாக உங்கள் சர்வருக்கு: ஒவ்வொரு பதிவுக்கும் JSON body உடன் ஒரு HTTP POST, விரும்பினால் keyword வடிகட்டியுடன்.

தாமதம் பற்றி நேர்மையாக: எங்கள் crawler ஒவ்வொரு சேனலையும் 3–14 நாட்களுக்கு ஒருமுறை பார்க்கிறது, எனவே பதிவுகள் தொகுப்பாக, பெரும்பாலும் வெளியான சில நாட்களுக்குப் பிறகு வரும். எங்களிடம் வந்த பின் சுமார் ஒரு நிமிடத்தில் வழங்கப்படும்; event-ல் அசல் தேதியும் delay_seconds-உம் இருக்கும். இது real-time feed அல்ல.

Endpoint-ஐ உருவாக்க டாஷ்போர்டு → Webhooks அல்லது கீழே உள்ள API-ஐப் பயன்படுத்தவும், பிறகு subscriptions சேர்க்கவும்: சேனல் பட்டியல் (id அல்லது @username) மற்றும் விருப்ப keywords — அவற்றில் ஏதேனும் இருந்தால் பதிவு வழங்கப்படும் (case-insensitive).

  • 2xx பதிலுடன் வழங்கப்பட்ட ஒவ்வொரு பதிவுக்கும் 0.5 கிரெடிட், key (அல்லது நிறுவனத்தின்) இருப்பிலிருந்து கழிக்கப்படும். நிர்வாகம், சோதனை ping, தோல்வியான முயற்சிகள் இலவசம். இருப்பு பூஜ்யமானால் delivery-கள் இழக்கப்படாது, 72 மணி நேரம் வரை காத்திருக்கும்.
  • எல்லா subscriptions-லும் கண்காணிக்கும் சேனல்கள்: Premium — 100, Business — 300, Super — 1,000. அதிகபட்சம் 5 endpoints, ஒவ்வொன்றிலும் 50 subscriptions.
GET/v1/webhooksSubscriptions உடன் endpoints; திட்ட வரம்பு மற்றும் 30 நாள் பயன்பாடு
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}]Delivery log, புதியது முதலில் (?status=, ?before_id=)
POST/v1/webhooks/{id}/deliveries/{delivery_id}/retryதோல்வியான அல்லது காலாவதியான delivery-ஐ மீண்டும் வரிசையில் சேர்
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 5 நிமிடங்களுக்கு மேல் வேறுபட்டால் request-ஐ நிராகரிக்கவும்.

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 பிழை exponential backoff உடன் மீண்டும் முயலப்படும் — 1, 2, 4… நிமிடங்கள், அதிகபட்சம் 6 மணி நேர இடைவெளி, 10 முயற்சிகள். Redirects பின்பற்றப்படாது. தோல்விகள் 24 மணி நேரம் தொடர்ந்தால் (குறைந்தது தொடர்ச்சியாக 20) endpoint முடக்கப்படும், owner-க்கு மின்னஞ்சல் வரும்; PATCH active=true மூலம் இயக்கவும், நிலுவையிலுள்ள delivery-கள் தொடரும்.
  • X-TGMarket-Idempotency-Key (= event id) மூலம் நகல்களை நீக்கவும்: ஒரு endpoint-க்கு ஒரு பதிவின் எல்லா முயற்சிகளிலும் இது ஒன்றே, ஒரு பதிவு ஒரு endpoint-க்கு இருமுறை வரிசையில் சேராது.
  • URL நிபந்தனைகள்: https மட்டும், பொது domain அல்லது IP; private, loopback, link-local முகவரிகள் (அனுப்பும்போது DNS தரும் முகவரிகளும்) நிராகரிக்கப்படும்; URL-ல் login/password கூடாது. விரைவாக 2xx பதில் அளித்து async-ஆக செயலாக்கவும்.