मुख्य सामग्री पर जाएं

​
अवलोकन

Enterprise यह एक एंटरप्राइज़ API है, जो केवल हमारे managed access levels में उपलब्ध है। इस API का उपयोग करने के लिए, आपको पहले हमारी enterprise sales team के साथ एक खाता सेट अप करना होगा। और जानें Engagement API, पोस्ट impression और engagement metrics तक पहुंच प्रदान करता है। हालांकि, अधिकांश metrics और endpoints के लिए आपको OAuth 1.0a User Context का उपयोग करके प्रमाणित करना होता है, लेकिन आप OAuth 2.0 बेयरर टोकन और /totals endpoint का उपयोग करके public Favorite, Retweet, Reply, और Video Views metrics तक पहुंच सकते हैं।   ध्यान दें: आप X के कुछ web dashboards पर रिपोर्ट किए गए डेटा और Engagement API में रिपोर्ट किए गए डेटा के बीच अंतर देख सकते हैं। ऐसा इसलिए होता है क्योंकि web dashboards आमतौर पर केवल वही engagements और/या impressions दिखाते हैं, जो चुनी गई समय-सीमा के भीतर हुए हों। उदाहरण के लिए, कोई web dashboard किसी कैलेंडर महीने की अवधि में पोस्ट्स पर engagement दिखा सकता है, जबकि Engagement API ऐसे engagements दिखा सकता है जो उस महीने की अवधि से बाहर हों, लेकिन अनुरोधित समय-सीमा के भीतर आते हों। ऐसे मामलों में Engagement API को ही मान्य स्रोत माना जाना चाहिए।  

​
अनुरोध एंडपॉइंट्स

Engagement API के तीन एंडपॉइंट हैं:

​
वर्तमान कुल: [/totals]

  • अनुरोध वांछित पोस्ट्स के लिए इम्प्रेशंस और एंगेजमेंट्स, दोनों के कुल मेट्रिक लौटाते हैं
  • निम्न मेट्रिक्स तक सीमित: Impressions, Engagements, Favorites, Replies, Retweets, Quote Tweets, और Video Views
  • OAuth 1.0a User Context का उपयोग करके पिछले 90 दिनों के भीतर बनाई गई पोस्ट्स के लिए Impressions और Engagements मेट्रिक्स प्राप्त किए जा सकते हैं
  • OAuth 2.0 बेयरर टोकन का उपयोग करके किसी भी पोस्ट के लिए Favorites, Retweets, Quote Tweets, Replies, और Video Views मेट्रिक्स प्राप्त किए जा सकते हैं
  • परिणाम, अनुरोध किए जाने के समय इम्प्रेशंस और एंगेजमेंट्स के वर्तमान कुल पर आधारित होते हैं
  • डैशबोर्ड रिपोर्ट को सक्षम बनाने और विभिन्न @हैंडलों में एंगेजमेंट दरों की गणना के लिए आदर्श
  • प्रति अनुरोध अधिकतम 250 पोस्ट्स के लिए मेट्रिक्स का अनुरोध किया जा सकता है  

​
पिछले 28 घंटे: [/28hr]

  • अनुरोध पिछले 28 घंटों में हुए इम्प्रेशंस का कुल मेट्रिक, एंगेजमेंट्स का कुल मेट्रिक, और अलग-अलग एंगेजमेंट मेट्रिक्स का विवरण लौटा सकते हैं
  • डेटा को पोस्ट ID के अनुसार समूहित किया जा सकता hai, और समय-श्रृंखला में समेकित रूप से, दिन के हिसाब से, या घंटे के हिसाब से भी दिखाया जा सकता है
  • हाल ही में बनाई गई सामग्री के प्रदर्शन को ट्रैक करने के लिए उपयुक्त
  • सभी उपलब्ध मेट्रिक्स का समर्थन करता है
  • प्रति अनुरोध अधिकतम 25 पोस्ट्स के लिए मेट्रिक्स का अनुरोध करने का समर्थन करता है  

​
ऐतिहासिक: [/historical]

  • अनुरोध इम्प्रेशन, एंगेजमेंट, और सबसे हाल के एक वर्ष के लिए अलग-अलग एंगेजमेंट मेट्रिक्स का विवरण लौटा सकते हैं। यह एंगेजमेंट के समय पर आधारित होता है (पोस्ट बनाए जाने के समय पर नहीं)।
  • अनुरोध start date और end date पैरामीटर का समर्थन करते हैं, जिससे 4 सप्ताह तक की किसी विशिष्ट समयावधि को चुनने की सुविधा मिलती है।
  • पोस्ट एंगेजमेंट डेटा केवल पिछले 365 दिनों तक उपलब्ध है।
  • डेटा को पोस्ट id के आधार पर समूहित किया जा सकता है, और टाइम-सीरीज़ में समग्र रूप से, दिन के अनुसार, या घंटे के अनुसार भी देखा जा सकता है।
  • हाल के प्रदर्शन की तुलना ऐतिहासिक मानक से करने या किसी @handle के प्रदर्शन की ऐतिहासिक तस्वीर तैयार करने के लिए उपयुक्त।
  • सभी उपलब्ध मेट्रिक्स का समर्थन करता है।
  • प्रति अनुरोध अधिकतम 25 पोस्ट्स के लिए मेट्रिक्स का अनुरोध करने का समर्थन करता है।

​
उपलब्ध मेट्रिक्स

नीचे दी गई तालिका उन मेट्रिक्स के प्रकारों का वर्णन करती है, जिन्हें Engagement API के माध्यम से एक्सेस किया जा सकता है। नीचे दिए गए मेट्रिक्स के बारे में अधिक जानने के लिए कृपया हमारा मेट्रिक्स की व्याख्या पेज देखें।
मेट्रिकएंडपॉइंट की उपलब्धताउपयोगकर्ता संदर्भ आवश्यकविवरण
इंप्रेशन्ससभीहाँपोस्ट को कितनी बार देखा गया, इसकी संख्या। यह मीट्रिक केवल उन पोस्ट्स के लिए उपलब्ध है जिन्हें पिछले 90 दिनों के भीतर पोस्ट किया गया है।
एंगेजमेंट्ससभीहाँकिसी उपयोगकर्ता ने पोस्ट के साथ कितनी बार इंटरैक्ट किया, इसकी संख्या। यह मीट्रिक केवल उन पोस्ट्स के लिए उपलब्ध है जिन्हें पिछले 90 दिनों के भीतर पोस्ट किया गया है।
पसंदसभीहाँ - /28hrs & /Historical

नहीं - /totals		पोस्ट को कितनी बार पसंद किया गया, इसकी संख्या।
रीट्वीटसभीहाँ - /28hrs & /Historical

नहीं - /totals		पोस्ट को कितनी बार रीट्वीट किया गया, इसकी संख्या।
quote_tweets/totalsनहीं - /totalsपोस्ट को टिप्पणी के साथ कितनी बार रीट्वीट किया गया, इसकी संख्या (इसे Quote भी कहा जाता है)।
जवाबसभीहाँ - /28hrs & /Historical

नहीं - /totals		पोस्ट को कितनी बार जवाब मिला है, इसकी संख्या।
video_viewsसभीहाँ - /28hrs & /Historical

नहीं - /totals		दिए गए पोस्ट में किसी वीडियो के कम-से-कम दो सेकंड तक 50% दिखाई देने की कुल संख्या.

वीडियो व्यूज़ केवल उन पोस्ट्स के लिए उपलब्ध हैं जो 1800 दिन पुराने या उससे कम पुराने हैं। यदि आप 1800 दिनों से अधिक पुराने किसी भी पोस्ट्स के लिए वीडियो व्यूज़ का अनुरोध करते हैं, तो आपको अपने रिस्पॉन्स में निम्न ऑब्जेक्ट प्राप्त होगा। इसके साथ एक अलग ऑब्जेक्ट भी होगा, जिसमें आपके द्वारा अनुरोधित अन्य मेट्रिक्स शामिल होंगे:

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

कृपया ध्यान दें: X के स्वामित्व और संचालन वाले प्लेटफ़ॉर्म्स (मोबाइल ऐप और वेबसाइट) पर दिखाए गए वीडियो व्यूज़ मेट्रिक और /28hr तथा /historical endpoints के माध्यम से आपको प्राप्त संख्या के बीच अंतर दिखाई दे सकता है।

* X user interface में और /totals endpoint के साथ दिखाए गए वीडियो व्यूज़, उन सभी पोस्ट्स में दिए गए वीडियो के लिए समेकित वीडियो व्यू दिखाते हैं जिनमें वह वीडियो पोस्ट किया गया है। इसका अर्थ है कि UI में दिखाए गए मेट्रिक में उन सभी स्थितियों के संयुक्त व्यूज़ शामिल होते हैं, जहाँ वीडियो को अलग-अलग पोस्ट्स में Retweet किया गया हो या दोबारा पोस्ट किया गया हो। इस मेट्रिक में gifs पर वीडियो व्यूज़ शामिल नहीं हैं।
* /28hr और /historical endpoints द्वारा दिए गए वीडियो व्यूज़ में केवल उसी विशिष्ट पोस्ट से उत्पन्न व्यूज़ शामिल होंगे, जिसके लिए आप मेट्रिक्स प्राप्त कर रहे हैं। इस मेट्रिक में gifs पर वीडियो व्यूज़ शामिल नहीं हैं।
media_views/28hr /historicalहाँवीडियो, GIF और इमेज में आपके मीडिया के सभी व्यूज़ (ऑटोप्ले और क्लिक) की कुल संख्या।
media_engagements

(पहले Media Clicks)		/28hr /historicalहाँपोस्ट में किसी इमेज या वीडियो जैसे मीडिया पर कितनी बार क्लिक किया गया, इसकी संख्या।
url_clicks/28hr /historicalहाँपोस्ट में किसी URL पर कितनी बार क्लिक किया गया, इसकी संख्या।
hashtag_clicks/28hr /historicalहाँपोस्ट में किसी हैशटैग पर कितनी बार क्लिक किया गया, इसकी संख्या।
detail_expands/28hr /historicalहाँपोस्ट को अधिक विवरण देखने के लिए कितनी बार क्लिक किया गया, उसकी संख्या।
permalink_clicks/28hr /historicalहाँपोस्ट के स्थायी लिंक (इस पोस्ट के लिए समर्पित अलग वेब पेज) पर कितनी बार क्लिक किया गया है, इसकी संख्या।
app_install_attempts/28hr /historicalहाँपोस्ट से ऐप इंस्टॉल इवेंट कितनी बार हुआ है, उसकी संख्या
app_opens/28hr /historicalहाँपोस्ट से ऐप ओपन इवेंट कितनी बार हुआ है, उसकी संख्या।
email_tweet/28hr /historicalहाँपोस्ट को ईमेल के ज़रिए कितनी बार साझा किया गया है, उसकी संख्या।
user_follows/28hr /historicalहाँइस पोस्ट से उपयोगकर्ता (पोस्ट लेखक) को कितनी बार फ़ॉलो किया गया, इसकी संख्या।
user_profile_clicks/28hr /historicalहाँइस पोस्ट से उपयोगकर्ता (पोस्ट लेखक) की प्रोफ़ाइल पर कितनी बार क्लिक किया गया, इसकी संख्या।

​
एंगेजमेंट समूहीकरण

समूहीकरण से लौटाए गए एंगेजमेंट मेट्रिक्स को कस्टम तरीके से व्यवस्थित किया जा सकता है। आप प्रत्येक अनुरोध में अधिकतम 3 समूहीकरण शामिल कर सकते हैं। आप मेट्रिक्स को निम्नलिखित में से एक या अधिक मानों के आधार पर समूहित कर सकते हैं: सभी तीनों एंडपॉइंट इसका समर्थन करते हैं:
  • tweet.id
  • engagement.type  
/28hr और /historical समय-श्रृंखला मेट्रिक्स प्रदान कर सकते हैं, इसलिए ये इसका भी समर्थन करते हैं:
  • engagement.day
  • engagement.hour
समूहीकरण के बारे में अधिक जानने के लिए, कृपया Guides अनुभाग में Engagement API Grouping पेज देखें।

​
मार्गदर्शिकाएँ

​
डेवलपर के लिए शुरुआती मार्गदर्शिका

​
परिचय

इस दस्तावेज़ का उद्देश्य डेवलपरों को Engagement API के साथ एकीकरण का परिचय कराना है। हम पहले एकीकरण के ‘क्यों’ पर चर्चा करेंगे, फिर ‘कैसे’ के तकनीकी विवरणों पर विस्तार से जाएंगे।
Engagement API क्या प्रदान करता है?
  • Engagement API पिछले 90 दिनों के दौरान किसी भी X खाते के स्वामित्व वाले पोस्ट्स के लिए impression और engagement डेटा प्रदान करता है, बशर्ते उस खाते ने 3-legged OAuth का उपयोग करके आपकी ऐप को अपनी ओर से metrics का अनुरोध करने की अनुमति दी हो। यह शक्तिशाली लेकिन लागू करने में आसान समाधान impressions और गहरे engagements, जैसे URL clicks, #hashtag clicks, आदि तक तुरंत पहुँच प्रदान करता है।
  • Engagement API किसी भी पोस्ट के लिए favorites, Retweets, Quote Tweets, replies और video views के कुल समेकित metrics प्रदान करता है। इसका उपयोग किसी भी पोस्ट या पोस्ट्स के संग्रह के बारे में बुनियादी engagement डेटा प्राप्त करने के एक प्रभावी तरीके के रूप में किया जा सकता है।
  • Engagement API, 15+ performance metrics का उपयोग करके सामग्री के प्रदर्शन को प्रभावी ढंग से मापने की सुविधा देकर, social listening, marketing और publishing platforms के लिए नया मूल्य प्रदान करता है, जिससे ग्राहक X पर ROI माप सकते हैं।
  • Engagement API एक request/response API है, जो ऐप डेवलपर्स को पोस्ट IDs, वांछित metrics और एक time frame के साथ अनुरोध भेजने की अनुमति देता है, जिसके जवाब में API तुरंत डेटा लौटाता है।  
एकीकृत क्यों करें? उदाहरण उपयोग के मामले
  • अपने कॉन्टेंट की कुल पहुँच को समझें, ताकि आप देख सकें कि उसे कितने लोग देखते हैं। यह भी देखें कि कितने लोग वीडियो देखते हैं, लिंक पर क्लिक करते हैं, हैशटैग पर क्लिक करते हैं, या मेरे ऐप्स इंस्टॉल करते हैं।
  • कुल और समय-श्रृंखला, दोनों तरह के एंगेजमेंट मेट्रिक्स जनरेट करें।
  • किसी भी सार्वजनिक पोस्ट के लिए बुनियादी एंगेजमेंट मेट्रिक्स (पसंद, Retweets, Quote Tweets, जवाब) समझें।
  • इन मेट्रिक्स का उपयोग यह तय करने के लिए करें कि किस तरह की पोस्ट्स बेहतर काम करती हैं, ताकि मैं उन्हें अधिक बार पोस्ट कर सकूँ और अपने कॉन्टेंट के लिए अधिक इम्प्रेशन और एंगेजमेंट प्राप्त कर सकूँ।
  • जब भी मेरी किसी पोस्ट को 100 Likes, या कोई अन्य सीमा, मिल जाए, तब मार्केटिंग गतिविधियों को स्वचालित करें (जैसे किसी दूसरे स्वामित्व वाले खाते से कॉन्टेंट को Retweet करना)।
  • A/B परीक्षण के लिए एक टूल के रूप में अपने अभियानों का बेंचमार्क करें और उनकी आपस में तुलना करें।
  • यह विश्लेषण करें कि आपके ग्राहक सेवा विभाग के लिए किस तरह का कॉन्टेंट सबसे अधिक प्रभावी है, ताकि यह तय किया जा सके कि कैसे और कब प्रतिक्रिया देनी है।
  • मेरे प्लेटफ़ॉर्म से प्रकाशित किए गए कॉन्टेंट के लिए एनालिटिक्स दिखाएँ।  
Engagement API को 2016 में लॉन्च किया गया था और यह पहला X API था, जिसने बड़े पैमाने पर ये विस्तृत एंगेजमेंट मेट्रिक्स उपलब्ध कराए। Engagement API का उपयोग करना आसान है और यह ग्राहकों को इस प्रक्रिया को स्वचालित करने में सक्षम बनाता है। यहाँ एक केस स्टडी है, जो एक उदाहरण एकीकरण का वर्णन करती है: अब जबकि हमने Engagement API के ‘क्यों’ को समझ लिया है, आइए तकनीकी विवरणों को समझना शुरू करें।

​
Engagement API को एकीकृत करना

API का परिचय
Engagement API एक सरल RESTful API है, जो JSON में एन्कोड किए गए अनुरोध प्राप्त करती है और JSON में एन्कोड किए गए एंगेजमेंट मेट्रिक्स के साथ जवाब देती है। अनुरोध तीन मुख्य भागों से मिलकर बनते हैं (अधिक दस्तावेज़ के लिए लिंक देखें):
  • पोस्ट IDs की array.
  • रुचि के metric types निर्दिष्ट करने वाली array. Types में ‘impressions’, ‘retweets’, ‘hashtag_clicks’ और ‘user_follows’ जैसी चीज़ें शामिल हैं।
  • Engagement groupings, जो एक JSON संरचना है और यह बताती है कि आप API response में engagement data को किस तरह व्यवस्थित करना चाहते हैं।
कई स्थितियों में, Engagement Types और Groupings एक अनुरोध से दूसरे अनुरोध तक अपेक्षाकृत स्थिर रहेंगे, और केवल पोस्ट IDs अपडेट किए जाएंगे। Engagement API three endpoints प्रदान करती है:
  • Totals - पोस्ट्स के लिए engagements का कुल योग प्रदान करता है। कुछ metrics सभी पोस्ट्स के लिए उपलब्ध होते हैं, जबकि अन्य केवल पिछले 90 दिनों के लिए उपलब्ध होते हैं।
  • 28 hour - पिछले 28 घंटों के time-series engagement metrics प्रदान करता है।
  • Historical - 1 सितंबर, 2014 के बाद किए गए पोस्ट्स के लिए अधिकतम लगातार चार सप्ताह तक के time-series engagement metrics प्रदान करता है।
/totals endpoint प्रति अनुरोध अधिकतम 250 Posts के metrics का अनुरोध करने का समर्थन करता है। /28hour और /historical endpoints प्रति अनुरोध 25 Posts का समर्थन करते हैं। Engagement API तक पहुंच प्राप्त करने पर चर्चा करने के बाद, हम API request बनाने की प्रक्रिया समझाएंगे, OAuth का एक संक्षिप्त अवलोकन देंगे, और अन्य तकनीकी संसाधनों के लिंक प्रदान करेंगे।
API ऐक्सेस प्राप्त करना
यदि आप यह दस्तावेज़ पढ़ रहे हैं, तो संभवतः आपको पहले ही Engagement API का ऐक्सेस मिल चुका है। यदि नहीं, तो कृपया अपने Enterprise account manager से संपर्क करें, या Enterprise ऐक्सेस के लिए यहाँ आवेदन करें। पहला चरण, एक स्वीकृत डेवलपर खाते का उपयोग करके डेवलपर कंसोल के माध्यम से X ऐप बनाना है। ऐक्सेस प्रदान करने के लिए आपके account manager को इस ऐप से संबद्ध संख्यात्मक App ID की आवश्यकता होगी। यदि आपको डेवलपर खाते के लिए आवेदन करना है, तो आप यहाँ ऐसा कर सकते हैं।
अनुरोध करना
अच्छी बात यह है कि Engagement API को अनुरोध भेजना आसान है। इस अनुरोध में, हम नीचे दिए गए @XDevelopers की इन दो पोस्ट्स के लिए कुल Retweets, Quote Tweets, Favorites और replies माँगेंगे:
1/ आज हम X API प्लेटफ़ॉर्म के भविष्य के लिए अपना विज़न साझा कर रहे हैंhttps://t.co/XweGngmxlP — Twitter Dev (@TwitterDev) 6 अप्रैल, 2017
अपने पोस्ट के बारे में पोस्ट्स देखना न चूकें। अब iOS पर, आप टिप्पणियों वाले Retweets को एक ही जगह पर देख सकते हैं। pic.x.com/oanjZfzC6y — X (@X) 12 मई, 2020
पहला चरण JSON में API अनुरोध तैयार करना है। इसमें इन दो पोस्ट id को एक array में रखा जाता है, रुचि के engagement types की एक array दी जाती है, और “groupings” नाम का एक कस्टम JSON object शामिल होता है, जो यह बताता है कि response में metrics को किस तरह व्यवस्थित करना है। हमारा अनुरोध इस प्रकार दिखता है: 
{
  "tweet_ids": [
    1260294888811347969, 850006245121695744
  ],
  "engagement_types": [
    "retweets", "quote_tweets", "favorites", "replies"
  ],
  "groupings": {
    "engagement-types-by-id": {
      "group_by": [
        "Tweet.id", "engagement.type"
      ]
    }
  }
}
इन कुल मेट्रिक्स को प्राप्त करने के लिए, हम यह JSON अनुरोध https://data-api.x.com/insights/engagement/totals endpoint पर POST करते हैं। हम यह बताने के लिए निम्नलिखित headers शामिल करेंगे कि हमारा अनुरोध JSON में encode किया गया है और यह Gzipped है (request body बड़ी हो सकती है):
  • Content-Type: application/json
  • Accept-Encoding: gzip  
अनुरोध करते समय, हम OAuth का उपयोग करके प्रमाणीकरण करते हैं, जिसके बारे में हम अगले अनुभाग में और विस्तार से चर्चा करेंगे। API निम्नलिखित payload लौटाता है: 
{
  "grouping name": {
    "1260294888811347969": {
      "favorites": "17111",
      "quote_tweets": "3254",
      "replies": "1828",
      "retweets": "5218"
    },
    "850006245121695744": {
      "favorites": "492",
      "quote_tweets": "66",
      "replies": "42",
      "retweets": "324"
    }
  }
}
ध्यान दें कि response में हमारे अनुरोधित metrics, “groupings” definitions में बताई गई संरचना के अनुसार मौजूद हैं, जहाँ metrics पहले पोस्ट ID के आधार पर सूचीबद्ध हैं, और फिर अगले स्तर पर engagement type के अनुसार। यह काफ़ी सरल था। अगर आप OAuth के साथ authentication करने में नए हैं, तो अगला अनुभाग देखें।

​
OAuth के साथ प्रमाणीकरण

OAuth एक प्रमाणीकरण मानक है, जो तकनीकी उद्योग में बहुत प्रचलित है। यदि आप पहले से OAuth का उपयोग कर रहे हैं (शायद अन्य X API के साथ), तो संभव है कि आप किसी भाषा-विशिष्ट OAuth पैकेज का इस्तेमाल कर रहे हों, जो इसकी सारी जटिलताओं को अपने भीतर संभाल लेता है। अगर आप OAuth में नए हैं, तो कृपया हमारे X API के साथ Oauth पेज पर जाएँ या अधिक जानकारी के लिए सीधे https://oauth.net देखें। इसके बाद, हम सलाह देते हैं कि आप अपनी पसंद की इंटीग्रेशन भाषा के लिए कोई OAuth पैकेज चुनें और वहीं से शुरुआत करें। इन पैकेजों के साथ, प्रमाणीकरण की प्रक्रिया आमतौर पर अपनी keys और tokens कॉन्फ़िगर करने, किसी प्रकार का HTTP ऑब्जेक्ट बनाने, और फिर उसी ऑब्जेक्ट से requests भेजने की होती है। उदाहरण के लिए, Ruby में नीचे दिया गया pseudo-code, Ruby gem ‘oauth’ का उपयोग करके OAuth-सक्षम ऐप बनाने और POST request करने का एक तरीका दिखाता है: 
require 'oauth'

#JSON अनुरोध तैयार करें (जैसा ऊपर बताया गया है)।
request = make_json_request()

#अपनी ऐप consumer key और secret के साथ एक ऐप consumer ऑब्जेक्ट बनाएं।
consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => ‘https://data-api.x.com’})
#अनुमति देने वाले अकाउंट द्वारा प्रदान किए गए tokens से user token बनाएं। यदि केवल ऐप-स्तरीय #अनुरोध कर रहे हैं (/totals endpoint के साथ ऐसे Tweets जांचना जिनके लिए अनुमति की आवश्यकता नहीं है), #तो यह चरण छोड़ा जा सकता है।
token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']}

#OAuth-सक्षम ऐप ऑब्जेक्ट बनाएं।
app = OAuth::AccessToken.from_hash(consumer, token)
#POST अनुरोध करें।
result = app.post(“/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"})
Engagement API, केवल-ऐप्लिकेशन और user-context, दोनों तरह के authentication का समर्थन करता है। यदि आप /totals endpoint के लिए ऐसे सार्वजनिक पोस्ट्स के engagement metrics एकत्र कर रहे हैं जो आपके स्वामित्व में नहीं हैं, तो किसी user permission की आवश्यकता नहीं होती और आप केवल-ऐप्लिकेशन authentication का उपयोग कर सकते हैं। इस स्थिति में, authentication के लिए आप केवल अपनी app key और secret का उपयोग करेंगे। OAuth किसी ऐप को उपयोगकर्ता से संबंधित tokens का उपयोग करके “किसी अन्य उपयोगकर्ता की ओर से” API request करने की भी अनुमति देता है। यदि आप स्वामित्व वाले पोस्ट्स के लिए Engagement metrics जनरेट कर रहे हैं, यानी ऐसे पोस्ट्स जो उस उपयोगकर्ता द्वारा प्रकाशित किए गए हैं जिसके user tokens आपके पास हैं, तो आप user context के साथ requests करेंगे, यानी authentication के लिए अपनी app keys और उपयोगकर्ता-विशिष्ट access tokens, दोनों का उपयोग करेंगे। ये user access tokens आम तौर पर ‘Sign-in with X’ प्रक्रिया के दौरान दिए जाते हैं या सीधे उपयोगकर्ता से प्राप्त किए जाते हैं (कृपया ध्यान दें कि यदि आप tokens सीधे उपयोगकर्ता से प्राप्त करते हैं, तो आपको twurl का उपयोग करना होगा)। एक बार उपयोगकर्ता अपने tokens प्रदान कर देता है, तो वे expire नहीं होते और उसकी ओर से requests करने के लिए Engagement API के साथ इस्तेमाल किए जा सकते हैं,  जब तक कि उपयोगकर्ता अपने tokens reset न कर दे या अपना password न बदल दे; ऐसी स्थिति में उसे आपको नए tokens देने होंगे। आप इस तालिका में देख सकते हैं कि किन metrics के लिए किस authentication की आवश्यकता होती है।

​
Engagement API एंडपॉइंट चुनना

Engagement API तीन अलग-अलग एंडपॉइंट उपलब्ध कराता है:
  • टोटल्स - ‘स्वामित्व वाले’ या ‘गैर-स्वामित्व वाले’ पोस्ट्स से चुने गए मेट्रिक्स के कुल योग उपलब्ध कराता है। कुछ मेट्रिक्स सभी पोस्ट्स के लिए उपलब्ध हैं, जबकि अन्य केवल पिछले 90 दिनों में प्रकाशित पोस्ट्स के लिए ही उपलब्ध हैं। प्रति अनुरोध 250 पोस्ट्स तक समर्थित हैं।
  • 28 घंटे - पिछले 28 घंटों के ‘स्वामित्व वाले’ पोस्ट्स के लिए समय-श्रृंखला Engagement मेट्रिक्स उपलब्ध कराता है। प्रति अनुरोध 25 पोस्ट्स तक समर्थित हैं।
  • ऐतिहासिक - 1 सितंबर, 2014 से किए गए ‘स्वामित्व वाले’ पोस्ट्स के लिए लगातार अधिकतम चार सप्ताह तक के समय-श्रृंखला Engagement मेट्रिक्स उपलब्ध कराता है। प्रति अनुरोध 25 पोस्ट्स तक समर्थित हैं।  
हर एंडपॉइंट की अपनी अलग विशेषताएं हैं। चाहे आप तीनों का उपयोग करने की योजना बना रहे हों, या यह तय कर रहे हों कि इनमें से कौन-सा आपके उपयोग के मामले के लिए सबसे उपयुक्त है, इनके बीच के अंतर को समझना महत्वपूर्ण है। नीचे हम कुछ प्रमुख अवधारणाओं का परिचय देते हैं, तीनों एंडपॉइंट्स को और विस्तार से समझाते हैं, और फिर ऐसे उदाहरण उपयोग के मामले प्रस्तुत करते हैं जो आम तौर पर किसी खास एंडपॉइंट से मेल खाते हैं। हमें उम्मीद है कि यह जानकारी आपको तीनों को अधिक कुशलता से इंटीग्रेट करने में मदद करेगी, या यह तय करने में सहायता करेगी कि कौन-सा एकल एंडपॉइंट आपकी ज़रूरत के लिए सबसे उपयुक्त है।  

​
मुख्य अवधारणाएँ

कई मुख्य अवधारणाएँ ऐसी हैं, जो तीनों Engagement API endpoints की अलग-अलग सुविधाओं और उनसे मिलने वाले डेटा को समझाने में मदद करती हैं।  
इंप्रेशन और एंगेजमेंट मेट्रिक्स
इंप्रेशन उस संख्या को दर्शाते हैं कि X प्लैटफ़ॉर्म पर किसी दिए गए पोस्ट को ऑर्गेनिक संदर्भ में कितनी बार देखा गया। Promoted या Paid संदर्भ में दिखाए गए पोस्ट्स से उत्पन्न इंप्रेशन इसमें शामिल नहीं होते। Engagement API से पहले, पोस्ट इंप्रेशन केवल संभावित व्यूज़ का एक माप थे। यह लेखक के अकाउंट के फ़ॉलोअर्स और उस सामग्री को Retweet करने वाले किसी भी अकाउंट के फ़ॉलोअर्स की संख्या पर आधारित था। इसमें उस सामान्य स्थिति को ध्यान में नहीं रखा जाता था, जब कोई उपयोगकर्ता वास्तव में पोस्ट देखता ही नहीं है। Engagement API द्वारा उत्पन्न इंप्रेशन मेट्रिक्स इस बात का वास्तविक माप हैं कि किसी पोस्ट को दिखाने के लिए वास्तव में कितनी बार रेंडर किया गया। यदि आपके अकाउंट का कोई फ़ॉलोअर आपका पोस्ट नहीं देख पाता, तो उसे इंप्रेशन में नहीं गिना जाता। Engagement API 14 विशिष्ट एंगेजमेंट मेट्रिक प्रकार के लिए मेट्रिक्स प्रदान करता है, जिनमें से प्रत्येक उस अलग कार्रवाई को दर्शाता है जो किसी उपयोगकर्ता के सामने पोस्ट प्रस्तुत होने पर वह कर सकता है। इनमें Retweet करना, Like करना, Reply करना, #hashtags, links और media जैसी entities पर क्लिक करना, लेखक को follow करना, और लेखक की प्रोफ़ाइल देखना शामिल है। इन सभी अलग-अलग कार्रवाइयों को मिलाकर एक ही Engagements मेट्रिक में शामिल किया जाता है।
स्वामित्व वाली और गैर-स्वामित्व वाली X सामग्री
Engagement, स्वामित्व वाली और गैर-स्वामित्व वाली पोस्ट्स के बीच स्पष्ट अंतर करता है। स्वामित्व वाली पोस्ट्स वे हैं जो आपके खाते से पोस्ट की गई हैं, या वे पोस्ट्स जिनके लिए आपने Engagement डेटा का अनुरोध करने की अनुमति प्राप्त की है। अन्य X API की तरह, आप यह अनुमति तब प्राप्त करते हैं जब अन्य X उपयोगकर्ता/खाते access token साझा करते हैं, जिससे आप उनकी ओर से API अनुरोध कर सकते हैं। ये token प्राप्त करने का एक सामान्य तरीका ‘Sign in with X’ process है। /totals endpoint, स्वामित्व वाली और गैर-स्वामित्व वाली दोनों तरह की पोस्ट्स के लिए engagement डेटा प्रदान करता है। गैर-स्वामित्व वाली पोस्ट्स के लिए, आप उन engagement metrics का अनुरोध कर सकते हैं जो किसी पोस्ट के प्रदर्शन में सार्वजनिक रूप से उपलब्ध होते हैं: Favorite, Retweet, और Reply। इन metrics के संदर्भ में, Engagement API की मुख्य उपयोगिता यह है कि यह आपको इन्हें स्वचालित तरीके से बड़े पैमाने पर प्राप्त करने की सुविधा देता है। स्वामित्व वाली पोस्ट्स के लिए, /totals endpoint Impression और (कुल) Engagement metrics भी प्रदान करता है। /28hr और /historical endpoints केवल स्वामित्व वाली पोस्ट्स के लिए metrics प्रदान करते हैं, यानी इन endpoints पर अनुरोध करते समय आपको user context भी भेजना होगा।
कुल और समय-श्रृंखला सहभागिता डेटा
/totals endpoint, जैसा कि इसके नाम से स्पष्ट है, अपने सहभागिता प्रकारों के लिए केवल कुल योग प्रदान करता है। इसके आंकड़े पोस्ट किए जाने के बाद से अब तक के अद्यतन कुल को दर्शाते हैं। यदि कोई पोस्ट अभी-अभी किया गया है और आप उसके मेट्रिक्स के लिए बार-बार अनुरोध करते हैं, तो ये कुल आमतौर पर हर अनुरोध के साथ बदलते रहेंगे। /28hr और /historical endpoints कुल योग और समय-श्रृंखला डेटा, दोनों प्रदान कर सकते हैं। समय-श्रृंखला डेटा का अनुरोध करते समय, एंगेजमेंट मेट्रिक्स को दैनिक या प्रति-घंटा डेटा में समेकित किया जा सकता है。   /28hr और /historical endpoints के साथ समय-श्रृंखला डेटा का अनुरोध कैसे करें, यह जानने के लिए सहभागिता समूहकरण पर हमारा दस्तावेज़ देखें।

​
एंडपॉइंट और उदाहरण उपयोग के मामले

ऊपर बताई गई विशेषताओं और अंतरों को देखते हुए, प्रत्येक एंडपॉइंट आम तौर पर अलग-अलग प्रकार के उपयोग के मामलों से जुड़ा होता है। यह तय करने में आपकी मदद के लिए कि आपके विशेष उपयोग के मामले के लिए कौन-सा एंडपॉइंट सबसे उपयुक्त है, नीचे कुछ उदाहरणात्मक उपयोगकर्ता कथन और उन्हें सबसे अच्छी तरह पूरा करने वाला एंडपॉइंट दिया गया है।
/totals
  • मुझे केवल कुछ मेट्रिक प्रकारों (Impressions, Engagements, Favorites, Retweets, Quote Tweets, Replies, और Video Views) तक पहुंच चाहिए।
  • मुझे किसी भी पोस्ट के लिए बुनियादी एंगेजमेंट डेटा चाहिए, सिर्फ मेरी अपनी पोस्ट्स के लिए नहीं।
  • मैं किसी प्रतिस्पर्धी की तुलना में प्रदर्शन देखना चाहता/चाहती हूँ।
  • मैं किसी हैशटैग या अभियान के लिए बुनियादी एंगेजमेंट आँकड़े ट्रैक करना चाहता/चाहती हूँ, जिसमें ऐसी पोस्ट्स शामिल हों जो मेरी नहीं हैं।
  • मुझे दिन या घंटे के हिसाब से विभाजित डेटा की जरूरत नहीं है; अनुरोध करते समय मुझे सिर्फ मौजूदा कुल चाहिए।
  • मुझे किसी रिपोर्ट या डैशबोर्ड में दिखाने के लिए एक ही मेट्रिक चाहिए, और मैं कोई डेटा स्टोर नहीं करना चाहता/चाहती।
  • मैं पेज लोड होने के समय डेटा दिखाना चाहता/चाहती हूँ, और इसके लिए मुझे सिर्फ एक अनुरोध करके उसका रिस्पॉन्स चाहिए।
  • मुझे हर दिन सैकड़ों हजारों या लाखों पोस्ट्स का डेटा पाने की सुविधा चाहिए।  
/28hr
  • मुझे सभी 17 मेट्रिक प्रकारों तक पहुंच चाहिए।
  • मैं पिछले 28 घंटों में प्रकाशित हुई हाल की पोस्ट्स का डेटा दिखाना चाहता हूँ।
  • मेरे पास एक जॉब है जो दिन में एक बार चलती है, ताकि मुझे ज़रूरी डेटा मिल सके, और मुझे केवल पिछले दिन का डेटा चाहिए।
  • मुझे मेट्रिक्स का विभाजन दिन या घंटे के हिसाब से चाहिए।
  • मैं डैशबोर्ड में घंटे के हिसाब से गतिविधि का time-series विभाजन दिखाना चाहता हूँ।
  • मुझे हर दिन सैकड़ों हज़ार पोस्ट्स के लिए उच्च एक्सेस चाहिए।
  • मेरे पास स्टोरेज की क्षमता है और मैं दिन में एक बार डेटा refresh करके चलता हुआ tally बनाए रख सकता हूँ।  
/historical
  • मुझे सभी 17 मेट्रिक प्रकार तक ऐक्सेस चाहिए।
  • मुझे सितंबर 2014 तक बनाए गए पोस्ट्स का ऐतिहासिक डेटा चाहिए।
  • मैं ऐसा विस्तृत ऐतिहासिक विश्लेषण दिखाना चाहता हूँ, जिसमें campaigns की तुलना की गई हो।
  • मुझे metrics दिन या घंटे के हिसाब से विभाजित चाहिए।
  • मुझे Engagement API तक उच्च-स्तरीय ऐक्सेस की आवश्यकता नहीं है और मुझे केवल प्रतिदिन कुछ सौ या हज़ार पोस्ट्स का डेटा चाहिए।

​
Engagement API की मुख्य विशेषताएँ

  • JSON डेटा देने वाला RESTful API, जो JSON डेटा बॉडी के साथ POST अनुरोधों का समर्थन करता है।
  • अनुरोधों के प्रकार: क्लाइंट ऐप्स निम्न प्रकार के अनुरोध कर सकते हैं:
    • कुल एंगेजमेंट्स — /totals endpoint पर HTTP POST अनुरोध
    • पिछले 28 घंटों के एंगेजमेंट्स — /28hr endpoint पर HTTP POST अनुरोध
    • ऐतिहासिक एंगेजमेंट्स — /historical endpoint पर HTTP POST अनुरोध
  • OAuth प्रमाणीकरण:
    • OAuth 1.0 User Context: 3-legged OAuth का उपयोग करके आपके ऐप को अधिकृत करने वाले उपयोगकर्ता के स्वामित्व वाली पोस्ट्स के लिए सभी उपलब्ध मेट्रिक्स उपलब्ध हैं। अनुरोध करते समय आपको उसी उपयोगकर्ता के Access Tokens का उपयोग करना होगा।
    • OAuth 2.0 बेयरर टोकन: चयनित मेट्रिक्स (Retweets, Quote Tweets, Replies, Favorites, और Video Views) किसी भी सार्वजनिक पोस्ट के लिए उपलब्ध हैं। 
  • अनुरोध metadata और संरचना: अनुरोध डेटा एक JSON ऑब्जेक्ट होता है, जिसमें Post ID की array, engagement प्रकारों की एक array, और एक engagement grouping संरचना शामिल होती है।
  • प्रति अनुरोध पोस्ट्स:
    • /totals endpoint: 250 Post IDs
    • /28hr endpoint: 25 Post IDs
    • /historical endpoint: 25 Post IDs
  • Engagement metrics की उपलब्धता:
    • /totals — पोस्ट प्रकाशित होने के बाद से metric totals। पिछले 90 दिनों में प्रकाशित पोस्ट्स के लिए Impressions और Engagements उपलब्ध हैं, जबकि Retweets, Quote Tweets, Replies, Favorites, और Video Views सभी पोस्ट्स के लिए उपलब्ध हैं।
    • /28hr — अनुरोध के समय से पिछले 28 घंटे।
    • /historical — 1 सितंबर, 2014 से शुरू होने वाली कोई भी 28-दिवसीय अवधि।
  • मेट्रिक प्रकार: प्रत्येक अनुरोध में मेट्रिक प्रकार की एक array शामिल होती है। इनकी उपलब्धता endpoint पर निर्भर करती है और, यदि /totals endpoint से अनुरोध किया जा रहा है, तो इस बात पर भी कि पोस्ट्स user-permissioned हैं या नहीं।
    • /totals endpoint:
      • सभी पोस्ट्स: Favorites, Retweets, Quote Tweets, Replies, और Video Views
      • OAuth 1.0a User Context आवश्यक: Impressions, Engagements, Favorites, Replies, और Retweets
    • /28hr और /historical endpoints (पोस्ट के स्वामी के Access Token के साथ OAuth 1.0a User Context आवश्यक): Impressions, Engagements, Favorites, Replies, Retweets, URL Clicks, Hashtag Clicks, Detail Click, Permalink Clicks, Media Clicks, App Install Attempts, App Opens, Post Emails, Video Views, और Media Views
  • Engagement समूहीकरण: प्रत्येक अनुरोध में Engagement समूहीकरण की एक array शामिल होती है। इन समूहीकरणों की मदद से आप यह अनुकूलित कर सकते हैं कि लौटाए गए metrics कैसे व्यवस्थित हों। प्रत्येक अनुरोध में अधिकतम तीन समूहीकरण शामिल किए जा सकते हैं। Metrics को निम्न मानों के आधार पर व्यवस्थित किया जा सकता है:
    • सभी endpoints: Post ID, Engagement Type
    • /28hr और /historical endpoints: यदि ये अतिरिक्त समूहीकरण निर्दिष्ट की जाती हैं, तो ये endpoints time-series प्रदान करते हैं: Engagement Day, Engagement Hour
  • इंटीग्रेशन अपेक्षाएँ: आपकी टीम निम्न के लिए ज़िम्मेदार होगी।
    • ऐसा क्लाइंट ऐप बनाना और बनाए रखना, जो Engagement API को HTTP requests भेज सके और अनुरोध में शामिल Post ID के लिए engagement metrics लौटा सके।
  • सीमाएँ
  • Video views केवल उन पोस्ट्स के लिए उपलब्ध हैं जो 1800 दिनों या उससे कम पुरानी हैं।

​
Engagement API के साथ प्रमाणीकरण

कृपया ध्यान दें:  API का उपयोग शुरू करने से पहले X को आपके डेवलपर ऐप के लिए Engagement API की ऐक्सेस सक्षम करनी होगी। इसके लिए, सुनिश्चित करें कि आप प्रमाणीकरण के लिए जिस App ID का उपयोग करना चाहते हैं, उसे अपने अकाउंट मैनेजर या तकनीकी सहायता टीम के साथ साझा करें।
Engagement API के साथ प्रमाणीकरण की दो विधियाँ उपलब्ध हैं: OAuth 1.0a और OAuth 2.0 बेयरर टोकन.  OAuth 2.0 बेयरर टोकन (जिसे “application-only” भी कहा जाता है) आपको सार्वजनिक रूप से उपलब्ध एंगेजमेंट मेट्रिक्स तक पहुँचने की अनुमति देता है। इस प्रमाणीकरण विधि का उपयोग /totals endpoint पर अनुरोध करते समय किसी भी सार्वजनिक रूप से उपलब्ध पोस्ट्स के लिए Favorites (यानी Likes), Retweets, Quote Tweets, Replies और वीडियो व्यूज़ की कुल संख्या प्राप्त करने के लिए किया जा सकता है।  OAuth 1.0a (जिसे “user context” भी कहा जाता है) आपको किसी उपयोगकर्ता की ओर से अनुरोध करने और उस उपयोगकर्ता से संबंधित निजी एंगेजमेंट मेट्रिक्स तक पहुँचने की अनुमति देता है।  यह प्रमाणीकरण विधि इन मामलों में आवश्यक है:
  • /28hr endpoint और /historical endpoint को भेजे गए सभी अनुरोधों के लिए
  • निम्नलिखित निजी मेट्रिक्स में से किसी भी मेट्रिक तक पहुँचने के लिए: Impressions, Engagements, Media Views, Media Engagements, URL Clicks, Hashtag Clicks, Detail Expands, Permalink Clicks, App Install Attempts, App Opens, Email Post, User Follows, और User Profile Clicks
OAuth 1.0a के साथ अनुरोध भेजते समय, आपको उस उपयोगकर्ता के Access Tokens (Access Token और Secret) शामिल करने होंगे जो संबंधित पोस्ट या संरक्षित संसाधन का स्वामी है। यदि आप संरक्षित उपयोगकर्ता डेटा का अनुरोध करते समय सही उपयोगकर्ता Access Tokens प्रदान नहीं करते हैं, तो Engagement API 403 Forbidden त्रुटि लौटाएगा। Engagement API आपको protected Posts के लिए एंगेजमेंट डेटा फ़ेच करने की अनुमति नहीं देगा, भले ही आप उन पोस्ट्स के स्वामी उपयोगकर्ता की ओर से प्रमाणीकरण कर रहे हों। ऐसा करने का प्रयास करने पर "Tweet ID(s) are unavailable" संदेश के साथ 400 Bad Request त्रुटि लौटेगी। यदि आप अपने स्वयं के X अकाउंट की ओर से अनुरोध भेज रहे हैं (दूसरे शब्दों में, वह अकाउंट जो डेवलपर ऐप का स्वामी है), तो आप आवश्यक Access Tokens सीधे Developer Console में डेवलपर ऐप के “Keys and tokens” टैब के अंतर्गत जनरेट कर सकते हैं। यदि आप किसी अन्य उपयोगकर्ता की ओर से अनुरोध कर रहे हैं, तो आवश्यक Access Tokens प्राप्त करने के लिए आपको 3-legged OAuth flow का उपयोग करना होगा। इसे कैसे करना है, इस बारे में अधिक जानकारी के लिए यह दस्तावेज़ देखें: OAuth 1.0a: उपयोगकर्ता के access tokens कैसे प्राप्त करें. अतिरिक्त उदाहरणों के लिए, जिनमें OAuth 1.0a का उपयोग करके प्रमाणीकरण करना भी शामिल है, XDevelopers sample Python code for the Engagement API देखें।

​
Engagement API में हाल के बदलाव

Engagement API मूल्यवान impression और engagement मेट्रिक्स प्रदान करता है, जिनकी मदद से आप X पर अपनी गतिविधि के प्रदर्शन की निगरानी कर सकते हैं। हमारे डेटा के आधार पर मार्केटिंग निर्णयों को सक्षम बनाने के अपने निरंतर प्रयास के तहत, हमें Engagement API में हुए हाल के बदलाव साझा करते हुए खुशी हो रही है, जो X के सभी हिस्सों में मेट्रिक्स के साथ बेहतर सुसंगति प्रदान करते हैं।   हमने हाल ही में Engagement API को आधुनिक बनाने के लिए बदलाव लागू किए हैं, ताकि यह X analytics dashboard (analytics.x.com) में उपयोग की जा रही वही metrics aggregation methodology इस्तेमाल करे। इन नए मेट्रिक्स को लागू करते समय breaking API changes को यथासंभव कम रखने के लिए हमने सावधानीपूर्वक तरीका अपनाया और बदलावों का पहला सेट 9 अक्टूबर, 2017 को लागू किया। ये बदलाव उन सभी जगहों पर सुसंगति बेहतर करते हैं, जहाँ आप या आपके ग्राहक X पर अपने प्रदर्शन की निगरानी कर सकते हैं। कृपया नीचे बदलावों का विस्तृत विवरण देखें:
मेट्रिकबदलाव
engagementsहमने overall engagements में शामिल मेट्रिक्स को अपडेट किया है, ताकि वे पोस्ट analytics dashboard के साथ सुसंगत रहें। Engagements यह मापता है कि “लोगों ने इस पोस्ट के साथ कितनी बार इंटरैक्ट किया”.

जिन पोस्ट्स में video या GIF जैसे media शामिल हैं, उनके लिए engagements metric में अब media views शामिल नहीं होंगे। Media views अब एक नए metric, media_views, में उपलब्ध हैं।
media_clicks*इस metric को “media_engagements” नाम के एक नए metric से बदल दिया गया है।
video_views6 जुलाई, 2018 से यह metric अब /totals endpoint के माध्यम से ‘unowned’ पोस्ट्स के लिए उपलब्ध है। इसका मतलब है कि आप app-only authentication का उपयोग करके सभी पोस्ट्स के लिए video views एक्सेस कर सकते हैं। 

आप केवल उन video views का अनुरोध कर सकते हैं जो 1800 दिनों से कम पुराने हों। अगर आप 1800 दिनों से अधिक पुराने किसी पोस्ट के लिए video views का अनुरोध करने का प्रयास करते हैं, तो आपको निम्न प्राप्त होगा:

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

कृपया ध्यान दें कि यह media_views से अलग होगा, क्योंकि video_views MRC standard पर आधारित है, जिसके अनुसार कम से कम दो सेकंड तक video का 50% भाग दृश्य में होना चाहिए।

साथ ही, ध्यान दें कि X के owned and operated platforms (mobile app और website) में प्रदर्शित video views metric और /28hr तथा /historical endpoints के माध्यम से प्राप्त संख्या के बीच आपको अंतर दिखाई दे सकता है।

* X user interface में प्रदर्शित और /totals endpoint द्वारा दिए गए video views, उस दिए गए video वाले सभी पोस्ट्स में समेकित video views दिखाएँगे। इसका मतलब है कि UI में प्रदर्शित metric में उन सभी instances के संयुक्त views शामिल होते हैं, जहाँ उस video को Retweet किया गया हो या अलग पोस्ट्स में फिर से पोस्ट किया गया हो।
* /28hr और /historical endpoints द्वारा प्रदान किए गए video views में केवल वही views शामिल होंगे, जो उस विशिष्ट पोस्ट से उत्पन्न हुए हैं जिसके लिए आप metrics प्राप्त कर रहे हैं।
media_viewsइसमें आपके media के सभी views (autoplay और click) शामिल हैं, जिन्हें videos, vines, gifs, और images में गिना जाता है।

कृपया ध्यान दें कि images वाले पोस्ट्स analytics dashboard में media_views metric नहीं दिखाते, लेकिन Engagement API में लौटाए जाएँगे।
media_engagements*इसमें videos, vines, gifs, और images में आपके media पर होने वाले clicks की संख्या शामिल है। यह metric media_clicks का स्थान ले रहा है।
quote_tweets7 जुलाई, 2020 से यह metric अब /totals endpoint के माध्यम से ‘unowned’ पोस्ट्स के लिए उपलब्ध है। इसका मतलब है कि आप app-only authentication का उपयोग करके सभी पोस्ट्स के लिए Quote Post count एक्सेस कर सकते हैं।

​
मेट्रिक्स की व्याख्या

नोट: आप X के कुछ वेब डैशबोर्ड पर दिखाए गए डेटा और Engagement API में रिपोर्ट किए गए डेटा के बीच अंतर देख सकते हैं। ये अंतर इसलिए होते हैं क्योंकि वेब डैशबोर्ड आम तौर पर केवल वही एंगेजमेंट और/या इम्प्रेशंस दिखाते हैं, जो चुनी गई समय-सीमा के भीतर हुए हों। उदाहरण के लिए, कोई वेब डैशबोर्ड किसी कैलेंडर माह के दौरान पोस्ट्स पर हुए एंगेजमेंट दिखा सकता है, जबकि Engagement API ऐसे एंगेजमेंट दिखा सकता है जो उस माह की अवधि से बाहर हों, लेकिन अनुरोधित समय-सीमा के भीतर आते हों। ऐसे मामलों में, Engagement API को मान्य स्रोत माना जाना चाहिए।  

​
इंप्रेशन और एंगेजमेंट डेटा

Engagement API ऑर्गेनिक इंप्रेशन और एंगेजमेंट डेटा प्रदान करता है। इंप्रेशन उस संख्या को दर्शाते हैं कि X प्लेटफ़ॉर्म पर किसी दिए गए पोस्ट को ऑर्गेनिक संदर्भ में कितनी बार देखा गया। Promoted या Paid संदर्भ में देखे गए पोस्ट्स से उत्पन्न इंप्रेशन शामिल नहीं होते। एंगेजमेंट उस संख्या को दर्शाते हैं कि किसी दर्शक ने किसी दिए गए पोस्ट के साथ ऑर्गेनिक और प्रमोटेड दोनों संदर्भों में कितनी बार इंटरैक्ट किया। एंगेजमेंट में Retweets, Favorites, Replies, URL Clicks, Hashtag Clicks, Mention Clicks और Media Views शामिल हैं, लेकिन ये इन्हीं तक सीमित नहीं हैं। शामिल एंगेजमेंट कार्रवाइयों की पूरी सूची के लिए, कृपया Engagement Data अनुभाग देखें।  आधारभूत एंगेजमेंट दर की गणना करने के लिए, जिस समयावधि का आप विश्लेषण कर रहे हैं उसमें किसी दिए गए पोस्ट के लिए कुल एंगेजमेंट को कुल इंप्रेशन से विभाजित करें। इंप्रेशन और एंगेजमेंट डेटा केवल स्वामित्व वाले @handles के पोस्ट्स के लिए, या उन @handles के लिए प्राप्त किया जा सकता है जिन्होंने आपके ऐप को अपने पोस्ट्स के बारे में विवरण देखने की अनुमति दी है।  आंतरिक रूप से, Engagement API अनुबंधित @handle सीमा के विरुद्ध अनुरोध किए गए अद्वितीय @handles की संख्या को ट्रैक करेगा।  यह भी अनुशंसित है कि आप पूरे महीने के दौरान क्लाइंट-साइड पर @handle अनुरोध उपयोग को ट्रैक करें।  

​
वीडियो मेट्रिक्स

X में मीडिया इम्प्रेशन्स को दर्शाने वाले कुछ अलग-अलग मेट्रिक्स हैं। इनमें पहला हमारा वीडियो व्यूज़ मेट्रिक है, जो MRC मानक पर आधारित है, जिसके अनुसार कम-से-कम दो सेकंड तक वीडियो का 50% हिस्सा स्क्रीन पर दिखाई देना चाहिए। दूसरा Media Views है, जिसमें आपके मीडिया के सभी व्यूज़ (autoplay और click) शामिल होते हैं, जिन्हें videos, vines, gifs, और images में गिना जाता है। वीडियो व्यूज़ मेट्रिक owned पोस्ट्स के लिए /28hour और /historical endpoints के माध्यम से उपलब्ध है, और सभी unowned पोस्ट्स के लिए /totals endpoint के माध्यम से भी उपलब्ध है।  हालाँकि X user interface में वीडियो व्यूज़ मेट्रिक भी उसी MRC मानक का उपयोग करता है, कृपया ध्यान दें कि X के owned and operated platforms (mobile app और website) पर दिखाए गए वीडियो व्यूज़ मेट्रिक और अलग-अलग Engagement API endpoints के माध्यम से प्राप्त संख्या में अंतर दिखाई दे सकता है।
  • /totals endpoint और X user interface द्वारा दिए गए वीडियो व्यूज़ उस वीडियो के लिए उन सभी पोस्ट्स में एकीकृत कुल वीडियो व्यूज़ दिखाते हैं, जिनमें वह वीडियो पोस्ट किया गया है। इसका मतलब है कि /totals के माध्यम से दिया गया और X UI में दिखाया गया मेट्रिक उन सभी अलग-अलग पोस्ट्स के संयुक्त व्यूज़ शामिल करता है, जहाँ उस वीडियो को Retweet या repost किया गया है।
  • /28hour और /historical Engagement API endpoints द्वारा दिए गए वीडियो व्यूज़ में केवल वही व्यूज़ शामिल होंगे, जो उस विशिष्ट पोस्ट से उत्पन्न हुए हैं जिसके लिए आप मेट्रिक्स प्राप्त कर रहे हैं।   
कृपया ध्यान दें कि हम 1800 दिनों से अधिक पुराने पोस्ट्स के लिए वीडियो व्यूज़ प्रदान नहीं करते। इसके बजाय, हम एक object प्रदान करते हैं, जिसमें उन पोस्ट्स की सूची होती है जो 1800 दिनों से अधिक पुराने हैं। आपके अनुरोधित पोस्ट्स के लिए अन्य सभी मेट्रिक्स आपको फिर भी एक अलग object में मिलेंगे। यहाँ एक example response है: 
{
  "unsupported_for_video_views_tweet_ids": [
    "479311209565413376",
    "477139122520219648"
  ],
  "grouping name": {
    "479311209565413376": {
      "favorites": "69",
      "impressions": "1692",
      "retweets": "142",
      "video_views": "0"
    },
    "477139122520219648": {
      "favorites": "10",
      "impressions": "1023",
      "retweets": "6",
      "video_views": "0"
    },
    "1397568983931392004": {
      "favorites": "268",
      "impressions": "26803",
      "retweets": "56",
      "video_views": "17902"
    }
  }
}
Media Views मेट्रिक केवल /28hour और /historical एंडपॉइंट्स के साथ स्वामित्व वाले पोस्ट्स के लिए उपलब्ध है।

​
Engagement API समूहीकरण

समूहीकरण, लौटाए गए एंगेजमेंट मेट्रिक्स को कस्टम तरीके से व्यवस्थित करने में सक्षम बनाते हैं। आप प्रत्येक अनुरोध में अधिकतम 3 समूहीकरण शामिल कर सकते हैं। आप निम्न में से एक या अधिक मानों के आधार पर मेट्रिक्स को समूहित कर सकते हैं: तीनों endpoints इनका समर्थन करते हैं:
  • tweet.id
  • engagement.type  
/28hr और /historical time-series मेट्रिक्स प्रदान कर सकते हैं, इसलिए ये इनका भी समर्थन करते हैं:
  • engagement.day
  • engagement.hour
समूहीकरण क्रमवार लागू किए जाते हैं, इसलिए आप अपने group_by मानों का क्रम बदलकर इच्छित परिणाम प्रारूप बदल सकते हैं। जिन समूहीकरणों में चार group_by मान होते हैं, वे केवल निम्नलिखित दो प्रारूपों में से किसी एक में ही समर्थित होते हैं:   
"group_by": [
    "tweet.id",
    "engagement.type",
    "engagement.day",
    "engagement.hour"
  ]
या 
"group_by": [
    "engagement.type",
    "tweet.id",
    "engagement.day",
    "engagement.hour"
]
उदाहरण के लिए, यदि आप metric type के समग्र कुल जनरेट करना चाहते हैं, तो अपने अनुरोध के हिस्से के रूप में निम्नलिखित “groupings” विनिर्देशन शामिल करें (और अनुरोधों को तैयार करने के बारे में अधिक जानकारी के लिए API संदर्भ पृष्ठ देखें):   
{
  "engagement_types": [
    "favorites",
    "replies",
    "retweets"
  ],
  "groupings": {
    "Grand Totals": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}
इस समूहकरण के साथ, Engagement API की JSON प्रतिक्रिया में रूट-स्तर का "Grand Totals" गुण शामिल होगा, जिसमें मेट्रिक्स type के अनुसार कुल योग शामिल होंगे: 
{
  "Grand Totals": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}
किसी एक पोस्ट के लिए, पोस्ट ID के अनुसार समूहीकृत मेट्रिक्स की 4-घंटे की time-series उत्पन्न करने हेतु, निम्नलिखित Grouping विनिर्देश अनुरोध का हिस्सा होगा: 
{
  "start": "2016-02-10T17:00:00Z",
  "end": "2016-02-10T21:00:00Z",
  "tweet_ids": [
    "697506383516729344"
  ],
  "engagement_types": [
    "impressions",
    "engagements"
  ],
  "groupings": {
    "Tweets_MetricType_TimeSeries": {
      "group_by": [
        "tweet.id",
        "engagement.type",
        "engagement.hour"
      ]
    }
  }
}
इस समूहीकरण के साथ, Engagement API के JSON response में root-level "Tweets_MetricType_TimeSeries" attribute शामिल होगा, जिसमें metrics को पहले पोस्ट ID, फिर metric type, और उसके अनुरूप प्रति-घंटा time-series के हिसाब से विभाजित किया गया होगा: 
{
  "Tweets_MetricType_TimeSeries": {
    "697506383516729344": {
      "impressions": {
        "2016-02-10": {
          "17": "551",
          "18": "412",
          "19": "371",
          "20": "280"
        }
      },
      "engagements": {
        "2016-02-10": {
          "17": "8",
          "18": "6",
          "19": "3",
          "20": "0"
        }
      }
    }
  }
}

​
अक्सर पूछे जाने वाले सवाल

Enterprise

​
Engagement API

Engagement API की पहुँच enterprise subscription के माध्यम से प्रदान की जाती है।  हमारी sales team से संपर्क करने के लिए कृपया यह फ़ॉर्म भरें।
यदि आपके contract में Engagement API के साथ उपयोग किए जा सकने वाले unique handles की संख्या की सीमा शामिल है, तो X का आंतरिक system Engagement API के माध्यम से query किए गए पोस्ट्स के मालिक Authenticated users की संख्या का रिकॉर्ड रखेगा।  ग्राहकों को client side पर भी इस unique संख्या का रिकॉर्ड रखना चाहिए।  वर्तमान में, Engagement API के लिए @handle उपयोग जाँचने हेतु कोई usage API या UI उपलब्ध नहीं है।  यदि contract में तय संख्या से अधिक @handles का अनुरोध किया जाता है, तो system overage को block नहीं करेगा।  billing month के अंत में, query किए गए unique @handles की संख्या की तुलना contract की गई मात्रा से की जाती है और contract की शर्तों के अनुसार overage charge किया जाएगा।
वर्तमान में, Engagement API के लिए @handle उपयोग जाँचने हेतु कोई usage API या UI उपलब्ध नहीं है।  यदि contract में तय संख्या से अधिक @handles का अनुरोध किया जाता है, तो system overage को block नहीं करेगा।  billing month के अंत में, query किए गए unique @handles की संख्या की तुलना contract की गई मात्रा से की जाती है और contract की शर्तों के अनुसार overage charge किया जाएगा।payload में लौटाया गया engagements metadata field सभी अलग-अलग engagement metric totals के योग के बराबर नहीं है। ऐसा क्यों है?यह अपेक्षित है। engagements metadata field हमेशा API द्वारा लौटाए गए सभी individual engagement metrics के कुल योग से मेल नहीं खा सकता। ऐसा इसलिए है क्योंकि engagements metadata field में ऐसे अतिरिक्त engagements शामिल हो सकते हैं जिनके लिए payload में अलग से कोई विशिष्ट metrics नहीं दिए गए होते। दूसरे शब्दों में, अलग-अलग engagement metric totals को जोड़ने पर जो मान मिलता है, वह ज़रूरी नहीं कि payload में लौटाए गए engagements metric field के मान के बराबर हो।आप engagements metadata field को पोस्ट पर किए गए किसी भी click या interaction के रूप में समझ सकते हैं।  payload response में url_clicks field एक संख्या लौटा रहा है, जबकि वास्तव में पोस्ट में कोई URL नहीं है। यह कैसे संभव है?ऐसा इसलिए हो सकता है कि किसी पोस्ट में hashtag जैसी कोई चीज़ हो, जो किसी दूसरे page का link बनाती है। यदि कोई user उस पर click करता है, तो उसे URL click के रूप में गिना जाएगा।  
किसी विशिष्ट पोस्ट के लिए engagement data प्राप्त न कर पाने के कई कारण हो सकते हैं, जिनमें शामिल हैं:
  • आपके द्वारा अनुरोधित Post ID या IDs उस authentication token के आधार पर उपलब्ध नहीं हैं, जिसका उपयोग आप किसी third party की ओर से data प्राप्त करने के लिए कर रहे हैं।
  • /totals endpoint के लिए आपके द्वारा अनुरोधित Post ID या IDs 90 दिन पुराने या उससे कम पुराने नहीं हैं, इसलिए impressions या engagement metrics लौटाने के लिए उपलब्ध नहीं हैं।
  • आपके द्वारा अनुरोधित Post ID या IDs अब उपलब्ध नहीं हैं, जो आमतौर पर यह दर्शाता है कि उन्हें delete कर दिया गया है या किसी अन्य कारण से वे अब publicly available नहीं हैं।
कृपया अलग-अलग error messages की समीक्षा करें, जो ऊपर बताए गए किसी भी मामले में आपको मिल सकते हैं।
Engagement API को request भेजते समय अपने consumption की निगरानी करने के लिए आप response header में लौटाई गई x-per-minute-limit और x-per-minute-remaining जानकारी का उपयोग कर सकते हैं।x-per-minute-limit बताता है कि आपकी allowance क्या है, और x-per-minute-remaining बताता है कि आपके पास कितनी calls बची हैं।

​
त्रुटि-निवारण मार्गदर्शिका

कृपया Engagement API के साथ प्रमाणीकरण संबंधी हमारे दिशानिर्देश देख लें।
[
    Your account could not be authenticated. Reason: Unknown Authorization Type;
]
सुनिश्चित करें कि /totals endpoint के साथ प्रमाणित करने का प्रयास करते समय आप कोई access token या secret इस्तेमाल न करें। ऐसा इसलिए है क्योंकि यदि आप ये token शामिल करते हैं और ऐसी पोस्ट से सामग्री प्राप्त करने का प्रयास कर रहे हैं जो इन token से संबद्ध नहीं है, तो आपको संभवतः इस तरह की त्रुटि मिलेगी:
[
    Forbidden to access tweets: 1054424731825229824;
]

​
अभी भी वह नहीं मिल रहा है जिसे आप खोज रहे हैं?

कृपया तकनीकी सहायता से संपर्क करें और हम आपको शीघ्र जवाब देंगे।

​
API संदर्भ

​
POST insights/engagement

​
विधियाँ

Methodविवरण
POST /insights/engagement/totalsTweets के संग्रह के लिए कुल इम्प्रेशन और एंगेजमेंट प्राप्त करें।
POST /insights/engagement/historical1 सितंबर 2014 तक पीछे जाकर, 4 सप्ताह तक की अवधि के लिए Tweets के संग्रह के इम्प्रेशन और एंगेजमेंट प्राप्त करें।
POST /insights/engagement/28hrपिछले 28 घंटों के लिए Tweets के संग्रह के इम्प्रेशन और एंगेजमेंट प्राप्त करें।

​
प्रमाणीकरण

Engagement API में HTTPS का उपयोग आवश्यक है और यह User Context तथा Application-Only OAuth, दोनों का समर्थन करता है। Engagement API के लिए अधिकांश अनुरोधों में 3-Legged OAuth (User Context का एक विशिष्ट संस्करण) का उपयोग करना आवश्यक होता है। इसका मतलब है कि आप उस ऐप की consumer key और secret का उपयोग करते हैं, जिसे आपके Twitter account manager ने Engagement API access के लिए पंजीकृत और स्वीकृत किया है। साथ ही, endpoint को कॉल करने के लिए Tweet मालिकों के access token और access token secret का भी उपयोग किया जाता है। निम्नलिखित अनुरोधों के लिए इस प्रकार के OAuth की आवश्यकता होती है:
  • Impressions और Engagements मेट्रिक प्रकार प्राप्त करने के लिए /totals पर कोई भी अनुरोध, जो केवल आपके स्वामित्व वाले Tweets तक सीमित हैं
  • /28hr पर कोई भी अनुरोध
  • /historical पर कोई भी अनुरोध
Engagement API के कुछ अनुरोध Application-Only OAuth का उपयोग करके किए जा सकते हैं। इसका अर्थ है कि आपको केवल अपनी consumer key और secret, या एक बेयरर टोकन प्रदान करना होगा। निम्नलिखित अनुरोध इस प्रकार के OAuth के साथ किया जा सकता है:
  • Favorites, Replies, Retweets, या Video Views मेट्रिक प्रकार प्राप्त करने के लिए /totals पर कोई भी अनुरोध, जिन्हें किसी भी Tweet के लिए प्राप्त किया जा सकता है
किसी भी अनुरोध के लिए, आपको developer.x.com पर उपलब्ध ऐप management console का उपयोग करके एक Twitter ऐप और उससे संबंधित API key सेट अप करनी होगी। कृपया ध्यान दें - यदि आप developer.x.com पर अपने Twitter खाते में लॉग इन हैं, तो आप Twitter apps को Twitter app dashboard के माध्यम से देख और संपादित कर सकते हैं। एक बार जब आप अपना ऐप सेट अप कर लेते हैं, तो Engagement API को अनुरोध भेजने के लिए आपके ऐप की ID को आपके account representative से स्वीकृति लेनी होगी। “current user” का प्रतिनिधित्व करने के लिए access tokens का उपयोग किया जाना चाहिए, और किसी अलग उपयोगकर्ता की ओर से किए गए अनुरोधों पर एक वैध token से हस्ताक्षर होना चाहिए। OAuth signature base strings तैयार करने से पहले यह सुनिश्चित करें कि आप URLs और POST bodies के भीतर reserved characters को encode सही तरीके से कर रहे हैं। OAuth के साथ शुरुआत करने के बारे में अधिक जानकारी के लिए, कृपया निम्नलिखित लिंक देखें:

​
POST /insights/engagement/totals

totals endpoint एक बार में अधिकतम 250 Tweet के संग्रह के लिए मौजूदा कुल impressions और engagements प्राप्त करने की सुविधा देता है।
अनुरोध की विधिHTTP POST
URLhttps://data-api.x.com/insights/engagement/totals
कंटेंट टाइपapplication/json
संपीड़नGzip. Gzip संपीड़न का उपयोग करके अनुरोध भेजने के लिए, कनेक्शन अनुरोध में Accept-Encoding हेडर भेजें।
हेडर इस प्रकार होना चाहिए:

Accept-Encoding: gzip
POST प्रारूपअनुरोधों को POST अनुरोध के रूप में भेजा जा सकता है, जहाँ बॉडी एक JSON ऑब्जेक्ट होती है, जिसमें Tweet IDs का एक संग्रह और इच्छित grouping शामिल होती है। POST को tweets, engagements, और groupings ऑब्जेक्ट के साथ एक array के रूप में फ़ॉर्मैट किया जाता है। प्रत्येक अनुरोध में अधिकतम 250 Tweet IDs शामिल हो सकती हैं।

POST बॉडी का एक उदाहरण इस प्रकार है:


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“favorites”,
“quote_tweets”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
Tweet IDsएक ऐरे, जिसमें उन Tweet की Tweet ID शामिल हों जिनके लिए एंगेजमेंट डेटा क्वेरी किया जाना है। कृपया ध्यान दें कि आप केवल उन्हीं Tweet के लिए डेटा का अनुरोध कर सकते हैं, जो प्रमाणित @handle द्वारा बनाए गए हों। प्रत्येक अनुरोध में अधिकतम 250 Tweet शामिल किए जा सकते हैं, और Tweet ID को स्ट्रिंग के रूप में दर्शाया जाना चाहिए।
एंगेजमेंट के प्रकारएक array, जिसमें क्वेरी किए जाने वाले एंगेजमेंट मेट्रिक्स के type शामिल होते हैं। Totals endpoint केवल निम्नलिखित engagement types का समर्थन करता है: impressions, engagements, favorites, retweets, quote_tweets, replies, video_views।
/totals endpoint पिछले 90 दिनों के भीतर बनाए गए Tweets के लिए impressions और engagements, तथा किसी भी Tweet के लिए favorites, retweets, quote_tweets, replies और video_views प्राप्त करने का समर्थन करता है।
समूहीकरणआपकी ज़रूरतों के अनुसार सबसे उपयुक्त रूप में Engagement API के परिणाम अलग-अलग समूहों में लौटाए जा सकते हैं। आप प्रत्येक अनुरोध में अधिकतम 3 समूहीकरण शामिल कर सकते हैं।

प्रत्येक समूहीकरण के लिए, आप एक कस्टम समूहीकरण नाम निर्धारित कर सकते हैं, ताकि आपके ऐप में इस समूहीकरण type का संदर्भ देना आसान हो जाए।

एक बार समूहीकरण नाम निर्धारित हो जाने पर, आप tweet.id और/या engagement.type के आधार पर समूह बना सकते हैं।

समूहीकरण क्रमवार लागू किए जाते हैं, इसलिए आप अपने group_by मानों का क्रम बदलकर इच्छित परिणाम प्रारूप बदल सकते हैं। एक उदाहरण समूहीकरण, जो Tweet ID और metric type के अनुसार अलग किए गए metrics दिखाता है, इस प्रकार है:


“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
POST की आकार-सीमाएक बार में अधिकतम 250 Tweet ID के लिए अनुरोध किया जा सकता है।
प्रतिक्रिया प्रारूपJSON. आपके अनुरोध के हेडर में प्रतिक्रिया के लिए JSON प्रारूप निर्दिष्ट होना चाहिए।
रेट लिमिटआपकी एक्सेस के स्तर के अनुसार, आपके अनुबंध में निर्दिष्ट सीमा के मुताबिक आप पर प्रति मिनट रेट लिमिट लागू होगी।
उदाहरण अनुरोध (पब्लिक मेट्रिक्स)curl —request POST
—url https://data-api.x.com/insights/engagement/totals
—header ‘accept-encoding: gzip’
—header ‘authorization: Bearer ’
—header ‘content-type: application/json’
—data ’{
“tweet_ids”: [
“1070059276213702656”,“1021817816134156288”,“1067094924124872705”
],
“engagement_types”: [
“favorites”,“retweets”,“replies”,“quote_tweets”,“video_views”
],
“groupings”: {
“perTweetMetricsUnowned”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
—verbose
—compressed
अनुरोध का उदाहरणcurl —request POST
—url https://data-api.x.com/insights/engagement/totals
—header ‘accept-encoding: gzip’
—header ‘authorization: OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
—header ‘content-type: application/json’
—data ’{
“tweet_ids”: [
“1060976163948904448”,“1045709644067471360”
],
“engagement_types”: [
“favorites”,“replies”,“retweets”,“video_views”,“impressions”,“engagements”
],
“groupings”: {
“perTweetMetricsOwned”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}’
—verbose
—compressed
उदाहरण प्रतिक्रिया (सार्वजनिक मेट्रिक्स){
“perTweetMetricsUnowned”: {
“1021817816134156288”: {
“favorites”: “530”,
“quote_tweets”: “79”,
“replies”: “147”,
“retweets”: “323”,
“video_views”: “0”
},
“1067094924124872705”: {
“favorites”: “1360”,
“quote_tweets”: “29”,
“replies”: “56”,
“retweets”: “178”,
“video_views”: “5754512”
},
“1070059276213702656”: {
“favorites”: “69”,
“quote_tweets”: “5”,
“replies”: “7”,
“retweets”: “26”,
“video_views”: “0”
}
}
}
उदाहरण रिस्पॉन्स{
“perTweetMetricsOwned”: {
“1045709644067471360”: {
“engagements”: “2”,
“favorites”: “0”,
“impressions”: “47”,
“replies”: “0”,
“retweets”: “8”,
“quote_tweets”: “5”,
“video_views”: “0”
},
“1060976163948904448”: {
“engagements”: “4”,
“favorites”: “0”,
“impressions”: “148”,
“replies”: “1”,
“retweets”: “9”,
“quote_tweets”: “2”,
“video_views”: “0”
}
}
}
अनुपलब्ध Tweet आईडीजिन क्वेरियों में ऐसे Tweet IDs शामिल हैं जो अब उपलब्ध नहीं हैं (उदाहरण के लिए, जिन्हें हटा दिया गया है), उनमें सभी उपलब्ध Tweet IDs के लिए उपयुक्त डेटा लौटाया जाएगा, और अनुपलब्ध Tweet IDs को unavailable_tweet_ids नामक एक array में सूचीबद्ध किया जाएगा। उदाहरण के लिए:

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:00:00Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: “26”,
“quote_tweets”: “2”
}
}
}

​
POST /insights/engagement/28hr

28 hour endpoint पिछले 28 घंटों के लिए अधिकतम 25 Tweets के संग्रह के impressions और engagements प्राप्त करने की सुविधा देता है। 28 hour endpoint सभी समर्थित individual metrics के लिए metrics का अनुरोध करने की सुविधा भी देता है। समर्थित metrics की पूरी सूची के लिए Metric Availability देखें।
अनुरोध विधिHTTP POST
URLhttps://data-api.x.com/insights/engagement/28hr
कंटेंट टाइपapplication/json
संपीड़नGzip. Gzip संपीड़न का उपयोग करके अनुरोध भेजने के लिए, कनेक्शन अनुरोध में Accept-Encoding header भेजें।
header निम्न जैसा होना चाहिए:

Accept-Encoding: gzip
POST प्रारूपअनुरोधों को POST अनुरोध के रूप में भेजा जा सकता है, जहाँ body एक JSON ऑब्जेक्ट होता है, जिसमें Tweet IDs का एक संग्रह और वांछित grouping शामिल होती है। POST को tweets, engagements, और groupings ऑब्जेक्ट वाले एक array के रूप में फ़ॉर्मैट किया जाता है। प्रत्येक अनुरोध में अधिकतम 25 Tweet IDs हो सकती हैं।

POST body का एक उदाहरण इस प्रकार है:


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.hour”
]
}
}
}
Tweet IDएक सरणी, जिसमें एंगेजमेंट डेटा के लिए क्वेरी की जाने वाली Tweet ID शामिल होती हैं। कृपया ध्यान दें कि आप केवल प्रमाणीकृत @handle द्वारा बनाए गए Tweet के लिए ही डेटा का अनुरोध कर सकते हैं। 28-घंटे वाला endpoint प्रति अनुरोध अधिकतम 25 Tweet का समर्थन करता है, और Tweet ID को string के रूप में दर्शाया जाना चाहिए।
एंगेजमेंट प्रकारजिन एंगेजमेंट मेट्रिक प्रकारों के लिए क्वेरी की जानी है, उनकी एक array।

28-घंटे के endpoint के लिए, impressions, engagements, और सभी अलग-अलग एंगेजमेंट प्रकार समर्थित मेट्रिक हैं। समर्थित एंगेजमेंट मेट्रिक की पूरी सूची के लिए एंगेजमेंट डेटा देखें।
समूहीकरणEngagement API के परिणाम आपकी आवश्यकताओं के अनुसार सबसे उपयुक्त रूप में अलग-अलग समूहों में लौटाए जा सकते हैं। आप प्रति अनुरोध अधिकतम 3 grouping शामिल कर सकते हैं।

प्रत्येक grouping के लिए, आप एक कस्टम grouping नाम परिभाषित कर सकते हैं, ताकि आपके ऐप में इस grouping type का संदर्भ देना आसान हो जाए। grouping नाम परिभाषित करने के बाद, आप निम्नलिखित में से एक या अधिक मानों के आधार पर समूह बना सकते हैं:
tweet.id
engagement.type
engagement.day
engagement.hour
Groupings को क्रमवार लागू किया जाता है, इसलिए आप अपने group_by मानों का क्रम बदलकर इच्छित परिणाम प्रारूप बदल सकते हैं। एक उदाहरण grouping, जो Tweet ID और metric type के आधार पर अलग किए गए metrics दिखाती है, इस प्रकार है:

“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


जिन Groupings में 4 group_by items होते हैं, वे केवल तभी मान्य हैं जब वे नीचे दिए गए दो क्रमों में से किसी एक का उपयोग करें। जिन अनुरोधों में किसी एक grouping में 4 group_by items हों, लेकिन उनका क्रम नीचे दिए गए क्रमों में से कोई न हो, वे त्रुटि लौटाएँगे। इसके अतिरिक्त, प्रति अनुरोध 4 group_by items वाली केवल एक grouping की अनुमति होगी।

“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]

“group_by”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
POST की आकार-सीमाएक बार में अधिकतम 25 Tweet ID के लिए अनुरोध किए जा सकते हैं।
प्रतिक्रिया प्रारूपJSON. आपके अनुरोध के header में response के लिए JSON format निर्दिष्ट होना चाहिए।
रेट लिमिटआपके access level के अनुसार, आपके contract में निर्दिष्ट सीमा के मुताबिक प्रति मिनट rate limit लागू होगी।
अनुरोध का उदाहरणcurl -X POST “https://data-api.x.com/insights/engagement/28hr”
-H ‘Accept-Encoding: gzip’
-H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
-d ’{
“tweet_ids”: [
“123456789”
],
“engagement_types”: [
“impressions”,
“engagements”
],
“groupings”: {
“hourly-time-series”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]
}
}
}‘
उदाहरण प्रतिक्रिया{
“start”:“2015-09-14T17:00:00Z”,
“end”:“2015-09-15T22:00:00Z”,
“hourly-time-series”:{
“123456789”:{
“impressions”:{
“2015-09-14”:{
“17”:“551”,
“18”:“412”,
“19”:“371”,
“20”:“280”,
“21”:“100”,
“22”:“19”,
“23”:“6”
},
“2015-09-15”:{
“00”:“5”,
“01”:“2”,
“02”:“7”,
“03”:“3”,
“04”:“1”,
“05”:“0”,
“06”:“0”,
“07”:“0”,
“08”:“0”,
“09”:“0”,
“10”:“0”,
“11”:“0”,
“12”:“0”,
“13”:“0”,
“14”:“0”,
“15”:“0”,
“16”:“0”,
“17”:“0”,
“18”:“0”,
“19”:“0”,
“20”:“0”,
“21”:“0”
}
},
“engagements”:{
“2015-09-14”:{
“17”:“0”,
“18”:“0”,
“19”:“0”,
“20”:“0”,
“21”:“0”,
“22”:“0”,
“23”:“0”
},
“2015-09-15”:{
“00”:“0”,
“01”:“0”,
“02”:“0”,
“03”:“0”,
“04”:“0”,
“05”:“0”,
“06”:“0”,
“07”:“0”,
“08”:“0”,
“09”:“0”,
“10”:“0”,
“11”:“0”,
“12”:“0”,
“13”:“0”,
“14”:“0”,
“15”:“0”,
“16”:“0”,
“17”:“0”,
“18”:“0”,
“19”:“0”,
“20”:“0”,
“21”:“0”
}
}
}
}
}
अनुपलब्ध Tweet IDsजिन क्वेरियों में ऐसे Tweet IDs शामिल हैं जो अनुपलब्ध हो चुके हैं (उदाहरण के लिए, हटा दिए गए हैं), उनमें सभी उपलब्ध Tweet IDs के लिए उपयुक्त डेटा लौटाया जाएगा, और अनुपलब्ध Tweet IDs को unavailable_tweet_ids नामक एक array में दर्शाया जाएगा। उदाहरण के लिए:

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:00:00Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: 26
}
}
}

​
POST /insights/engagement/historical

historical endpoint 4 सप्ताह तक की किसी भी अवधि के लिए अधिकतम 25 Tweets के संग्रह की impressions और engagements प्राप्त करने की सुविधा देता है। वर्तमान में, 1 सितंबर 2014 से पुराने डेटा का अनुरोध API से नहीं किया जा सकता। historical endpoint सभी समर्थित individual metrics के लिए metrics का अनुरोध करने की सुविधा भी देता है। समर्थित metrics की पूरी सूची के लिए Metric Availability देखें।
अनुरोध विधिHTTP POST
URLhttps://data-api.x.com/insights/engagement/historical
कंटेंट टाइपapplication/json
संपीड़नGzip. Gzip संपीड़न का उपयोग करके अनुरोध भेजने के लिए, कनेक्शन अनुरोध में Accept-Encoding हेडर भेजें।
हेडर निम्न जैसा होना चाहिए:

Accept-Encoding: gzip
POST प्रारूपअनुरोधों को POST अनुरोध के रूप में भेजा जा सकता है, जिसमें body एक JSON object होता है, जिसमें Tweet IDs का एक संग्रह और वांछित grouping शामिल होती है। POST का प्रारूप एक array के रूप में होता है, जिसमें tweets, engagements, और groupings object शामिल होते हैं। प्रत्येक अनुरोध में अधिकतम 25 Tweet IDs हो सकती हैं। प्रत्येक अनुरोध के लिए अधिकतम चार सप्ताह की अवधि तक कस्टम Start और End date निर्दिष्ट की जा सकती है।


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.hour”
]
}
}
}
प्रारंभ और समाप्ति दिनांकअनुरोध के हिस्से के रूप में start और end मानों का उपयोग करके कस्टम प्रारंभ और समाप्ति तिथि निर्दिष्ट की जा सकती है। आपको ऐसी प्रारंभ और समाप्ति तिथियाँ निर्दिष्ट करनी होंगी जिनकी अवधि 4 सप्ताह से अधिक न हो। इस समय संभव सबसे पुरानी प्रारंभ तिथि 1 सितंबर, 2014 है। भविष्य की समाप्ति तिथियाँ समर्थित नहीं हैं। यदि कोई Start और End तिथि प्रदान नहीं की जाती है, तो API डिफ़ॉल्ट रूप से उससे ठीक पहले के 4 सप्ताह का उपयोग करेगा।

Engagement API से डेटा अधिकतम घंटे-स्तर की ग्रैन्युलैरिटी पर लौटाया जा सकता है। जिन अनुरोधों में Start या End मान ठीक घंटे की सीमा पर नहीं आते, वे डिफ़ॉल्ट रूप से निकटतम समावेशी घंटे पर सेट हो जाएंगे। उदाहरण के लिए, “start”:“2015-07-01T12:24:00Z” और “end”:“2015-07-10T08:37:00Z” वाला अनुरोध डिफ़ॉल्ट रूप से “start”:“2015-07-01T12:00:00Z”,“end”:“2015-07-10T09:00:00Z” हो जाएगा।
Tweet आईडीएक ऐरे, जिसमें उन Tweets के Tweet IDs शामिल हैं जिनके लिए एंगेजमेंट डेटा क्वेरी किया जाना है। कृपया ध्यान दें कि आप केवल प्रमाणीकृत @handle द्वारा बनाए गए Tweets के लिए ही डेटा का अनुरोध कर सकते हैं। 4-सप्ताह वाला historical endpoint प्रति अनुरोध अधिकतम 25 Tweets का समर्थन करता है, और Tweet IDs को strings के रूप में दर्शाया जाना चाहिए।
एंगेजमेंट के प्रकारएक array जिसमें क्वेरी की जाने वाली सहभागिता मेट्रिक्स के प्रकार शामिल होते हैं।

4-सप्ताह वाले historical endpoint के लिए, impressions, engagements और सभी अलग-अलग सहभागिता प्रकार समर्थित मेट्रिक्स हैं। समर्थित सहभागिता मेट्रिक्स की पूरी सूची के लिए Engagement Data देखें।

नोट: वर्तमान में तीन मेट्रिक्स ऐसे हैं जो 15 सितंबर, 2015 से पहले की गई क्वेरी के लिए शून्य के रूप में प्रदर्शित होंगे: favorites, replies और retweets.
समूहीकरणEngagement API के परिणाम आपकी आवश्यकताओं के अनुसार अलग-अलग समूहों में लौटाए जा सकते हैं। आप हर अनुरोध में अधिकतम 3 groupings शामिल कर सकते हैं।

हर grouping के लिए, आप एक कस्टम grouping नाम तय कर सकते हैं, ताकि आपके ऐप में इस grouping type का संदर्भ देना आसान हो जाए। grouping नाम तय करने के बाद, आप निम्नलिखित में से एक या अधिक मानों के आधार पर समूह बना सकते हैं:
tweet.id
engagement.type
engagement.day
engagement.hour
Groupings को क्रमवार लागू किया जाता है, इसलिए आप अपने group_by मानों का क्रम बदलकर इच्छित परिणाम प्रारूप बदल सकते हैं। एक उदाहरण grouping, जो metrics को Tweet ID और metric type के अनुसार अलग-अलग दिखाती है, इस प्रकार है:

“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


जिन groupings में 4 group_by items होते हैं, वे केवल तभी मान्य हैं जब वे नीचे दिए गए दो क्रमों में से किसी एक का उपयोग करें। जिन अनुरोधों में किसी एक grouping में 4 group_by items हों, लेकिन उनका क्रम नीचे दिए गए क्रमों में से कोई न हो, वे त्रुटि लौटाएँगे। इसके अतिरिक्त, हर अनुरोध में 4 group_by items वाली केवल एक grouping की अनुमति है।

“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]

“group_by”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
POST की सीमाएक बार में अधिकतम 25 Tweet IDs के लिए अनुरोध किए जा सकते हैं।
प्रतिक्रिया प्रारूपJSON। आपके अनुरोध के header में response के लिए JSON format निर्दिष्ट होना चाहिए।
रेट लिमिटआपके access level के अनुसार, आपके अनुबंध में निर्दिष्ट सीमा के तहत प्रति मिनट rate limit लागू होगी।
अनुरोध का उदाहरणcurl -XPOST “https://data-api.x.com/insights/engagement/historical”
-H ‘Accept-Encoding: gzip’
-H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
-d ’{
“start”: “2015-08-01”,
“end”: “2015-08-15”,
“tweet_ids”: [
“123456789”,
“223456789”,
“323456789”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“types-by-tweet-id”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}‘
उदाहरण प्रतिक्रिया{
“start”: “2015-08-01T00:00:00Z”,
“end”: “2015-08-15T00:00:00Z”,
“types-by-tweet-id”: {
“123456789”: {
“impressions”: “0”,
“engagements”: “0”,
“url_clicks”: “0”,
“detail_expands”: “0”
},
“223456789”: {
“impressions”: “788”,
“engagements”: “134”,
“url_clicks”: “30”,
“detail_expands”: “1323”
},
“323456789”: {
“impressions”: “4”,
“engagements”: “0”,
“url_clicks”: “2”,
“detail_expands”: “0”
}
}
}
अनुपलब्ध Tweet IDsऐसी क्वेरियों के लिए जिनमें वे Tweet IDs शामिल हैं जो अनुपलब्ध हो चुके हैं (उदाहरण के लिए, जिन्हें हटा दिया गया है), सभी उपलब्ध Tweet IDs के लिए उपयुक्त डेटा लौटाया जाएगा, और अनुपलब्ध Tweet IDs का उल्लेख unavailable_tweet_ids नामक एक array में किया जाएगा। उदाहरण के लिए:

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:27:50Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: 26
}
}
}

​
प्रतिक्रिया कोड

StatusTextDescription
200OKअनुरोध सफल रहा।
400Bad Requestआम तौर पर, यह प्रतिक्रिया तब मिलती है जब अनुरोध में अमान्य JSON हो, या अनुरोध के साथ कोई JSON payload भेजा ही न गया हो।
401Unauthorizedअमान्य क्रेडेंशियल्स के कारण HTTP प्रमाणीकरण विफल हो गया। अपनी OAuth कुंजियाँ और टोकन जाँचें।
404Not Foundजिस URL पर अनुरोध भेजा गया था, वहाँ संसाधन नहीं मिला। संभवतः गलत URL का उपयोग किया गया था।
429Too Many Requestsआपका ऐप API अनुरोधों की सीमा से अधिक जा चुका है।
500Internal Server ErrorGnip की ओर से त्रुटि हुई। exponential backoff पैटर्न का उपयोग करके अपना अनुरोध फिर से आज़माएँ।
502Proxy ErrorGnip की ओर से त्रुटि हुई। exponential backoff पैटर्न का उपयोग करके अपना अनुरोध फिर से आज़माएँ।
503Service UnavailableGnip की ओर से त्रुटि हुई। exponential backoff पैटर्न का उपयोग करके अपना अनुरोध फिर से आज़माएँ।

​
त्रुटि संदेश

विभिन्न परिस्थितियों में, Engagement API प्रसंग-विशिष्ट त्रुटि संदेश लौटा सकता है, जिनसे निपटने के लिए आपके एप्लिकेशन को तैयार होना चाहिए। नीचे दी गई तालिका में इन त्रुटि संदेशों के सामान्य उदाहरण और उनकी व्याख्या करने का तरीका दिया गया है। कृपया ध्यान दें कि कई मामलों में Engagement API, अधिक जानकारी के साथ 200 OK response के हिस्से के रूप में, उपलब्ध data के लिए विशिष्ट त्रुटि संदेशों सहित आंशिक परिणाम लौटाता है।
Error MessageDescription
"errors":["Your account could not be authenticated. Reason: Access token not found"]अनुरोध के authentication component में त्रुटि है। “Reason” में ऐसी जानकारी होनी चाहिए जो त्रुटि के निवारण में सहायक हो। यदि आप समस्या का समाधान नहीं कर पाते हैं, तो कृपया “Reason” सहित पूरी त्रुटि हमारी support team को भेजें।
"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"]आपके द्वारा अनुरोधित Tweet ID या IDs अब उपलब्ध नहीं हैं। आमतौर पर इसका अर्थ है कि उन्हें हटा दिया गया है या किसी अन्य कारण से वे अब सार्वजनिक रूप से उपलब्ध नहीं हैं।
"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]/totals endpoint के लिए आपके द्वारा अनुरोधित Tweet ID या IDs 90 दिन या उससे नए नहीं हैं, इसलिए उनके लिए impressions या engagements metrics उपलब्ध नहीं कराए जा सकते।
"errors":["Forbidden to access tweets: *TWEET_IDS*"]आपके द्वारा अनुरोधित Tweet ID या IDs, किसी third party की ओर से data प्राप्त करने के लिए उपयोग किए जा रहे authentication token के आधार पर उपलब्ध नहीं हैं।