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_xxxxxxxxxxxxxxxxScopes: 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
| Method | Path | விளக்கம் | விலை |
|---|---|---|---|
| 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 | எண்ணிக்கைகள் மற்றும் facets | request |
| 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/advertisers | 30 நாட்களில் சேனல்களின் எண்ணிக்கைப்படி விளம்பரதாரர்கள் (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/exports | Async Export (export scope) | Export விலை |
| POST | /v1/exports/quote | ஆர்டருக்கு முன் ஏற்றுமதி விலை: வரிசைகள், இலவச வரிசைகள், தள்ளுபடிகள் | request |
| GET | /v1/exports/{id} | நிலை மற்றும் பதிவிறக்க இணைப்பு | இலவசம் |
| GET | /v1/feeds | Enterprise: தினசரி feed நாட்கள் (புதிய, மாற்றப்பட்ட, நீக்கப்பட்ட சேனல்கள், Parquet) | இலவசம் |
| GET | /v1/feeds/{date} | Enterprise: அன்றைய கோப்புக்கான கையொப்பமிட்ட இணைப்பு (export scope) | அன்றைய வரிசைகள் ஒப்பந்த விகிதத்தில், ஒருமுறை |
ஃபில்டர்கள் (ChannelQuery)
/channels/search, /channels/count மற்றும் /exports-க்கு query object ஒன்றே. காலியான ஃபீல்டுகளை விட்டுவிடுங்கள்.
| 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 | செயலில் உள்ள கமெண்டர்கள்: விவாத chat-இல் தனித்துவமான ஆசிரியர்கள், 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 | flags (இயல்பாக 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": ["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— தவறான அல்லது ரத்து செய்யப்பட்ட 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— தவறான 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/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}] | 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-ஆக செயலாக்கவும்.