Usage API

Usage API एक निःशुल्क REST API है, जो आपके एंटरप्राइज़ खाते के लिए विभिन्न उत्पादों में खपत गतिविधि की प्रोग्रामेटिक पहुँच और दृश्यता प्रदान करती है।

Usage API | Twitter API

अवलोकन

Enterprise

यह आपके खाते के अंतर्गत विभिन्न API में उपयोग की निगरानी और प्रबंधन में मदद करने के लिए सबसे महत्वपूर्ण और सबसे अच्छा टूल है।

महत्वपूर्ण अस्वीकरण:

Usage API से लौटाई गई उपयोग गणनाएँ, ट्रायल और अन्य बिलिंग समायोजनों के कारण, बिलिंग इनवॉइस पर दिखाई गई गणनाओं से मेल नहीं खा सकतीं। सभी संख्याएँ किसी दिए गए दिन (UTC में) के भीतर उपभोग की गई डीडुप की गई गतिविधियों पर आधारित हैं।

सुविधाएँ

• console.gnip.com UI में उपलब्ध उपयोग डेटा को प्रोग्रामेटिक तरीके से प्राप्त करना
• स्ट्रीम-स्तर का उपयोग डेटा - यह उत्पाद-स्तर के अलावा स्ट्रीम-स्तर (जैसे, dev और prod) पर भी उपयोग डेटा प्रदान करता है
• विस्तृत और वर्णनात्मक डेटा - खोज “requests” को Full-Archive और 30-Day Search उत्पादों के अनुसार अलग-अलग दिखाया जाता है
• ऐतिहासिक PowerTrack “days” और “jobs” 

समर्थित APIs

नीचे उन APIs की सूची दी गई है, जिन्हें वर्तमान में Usage API समर्थन करता है:

• PowerTrack API enterprise
• 30-Day Search API enterprise
• Full-Archive Search API enterprise
• Historical PowerTrack enterprise

सीमाएँ

• Usage API आपको 1 मई, 2018 से उपयोग डेटा तक पहुँचने की अनुमति देता है। 1 जुलाई, 2019 के बाद, Usage API आपको पिछले 13 कैलेंडर महीनों के उपयोग डेटा तक पहुँचने की अनुमति देता है

• आप fromDate और toDate द्वारा परिभाषित तीन-महीने के अंतरालों में उपयोग डेटा तक पहुँच सकते हैं

अनुरोध और रिस्पॉन्स के लिए नीचे देखें:

curl -u<username>:<password> \
"https://gnip-api.x.com/metrics/usage/accounts/<account-name>.json?bucket=month"

{
  "account": {
    "name": "accountnamehere"
  },
  "publishers": [
    {
      "type": "twitter",
      "used": [
        {
          "timePeriod": "201805010000",
          "activities": 1235,
          "searchRequests30Day": 3,
          "searchRequestsFullArchive": 19,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        },
        {
          "timePeriod": "201806010000",
          "activities": 23467,
          "searchRequests30Day": 0,
          "searchRequestsFullArchive": 66,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        },
        {
          "timePeriod": "201807010000",
          "activities": 431,
          "searchRequests30Day": 11,
          "searchRequestsFullArchive": 4,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        }
      ],
      "projected": {
        "timePeriod": "201807010000",
        "activities": 803,
        "searchRequests30Day": 20,
        "searchRequestsFullArchive": 7,
        "historicalPowertrackDays": 0,
        "historicalPowertrackJobs": 0
      },
      "products": [
        {
          "type": "Historical PowerTrack Subscription",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201806010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201807010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 0,
            "days": 0,
            "jobs": 0
          }
        },
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 267
            },
            {
              "timePeriod": "201806010000",
              "activities": 3
            },
            {
              "timePeriod": "201807010000",
              "activities": 32
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 59
          },
          "endpoints": [
            {
              "type": "PowerTrack 2.0",
              "label": "actformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 0
              }
            },
              {
              "type": "PowerTrack Replay 2.0",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 0
              }
            }
          ]
        },
        {
          "type": "Search API (30-Day) 2.0",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 10,
              "searchRequests30Day": 3
            },
            {
              "timePeriod": "201806010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201807010000",
              "activities": 23,
              "searchRequests30Day": 11
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 42,
            "searchRequests30Day": 20
          },
          "endpoints": [
            {
              "type": "Search API (30-Day) 2.0",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 10,
                  "searchRequests30Day": 3
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 21,
                  "searchRequests30Day": 10
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 39,
                "searchRequests30Day": 18
              }
            }
          ]
        },
        {
          "type": "Search API (Full-Archive)",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 961,
              "searchRequestsFullArchive": 19
            },
            {
              "timePeriod": "201806010000",
              "activities": 23466,
              "searchRequestsFullArchive": 66
            },
            {
              "timePeriod": "201807010000",
              "activities": 379,
              "searchRequestsFullArchive": 4
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 706,
            "searchRequestsFullArchive": 7
          },
          "endpoints": [
            {
              "type": "Search API (Full-Archive)",
              "label": "actformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 1,
                  "searchRequestsFullArchive": 3
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 2,
                  "searchRequestsFullArchive": 1
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 3,
                "searchRequestsFullArchive": 1
              }
            },
            {
              "type": "Search API (Full-Archive)",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 961,
                  "searchRequestsFullArchive": 16
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 23466,
                  "searchRequestsFullArchive": 66
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 379,
                  "searchRequestsFullArchive": 3
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 706,
                "searchRequestsFullArchive": 5
              }
            }
          ]
        }
      ]
    }
  ],
  "bucket": "month",
  "fromDate": "201805010000",
  "toDate": "201808010000"
}

नमूना पेलोड

नीचे पेलोड का एक उदाहरण दिया गया है:

{
  "account": {
    "name": "gnip-username"
  },
  "bucket": "month",
  "publishers": [
    {
      "type": "automattic",
      "used": [
        {
          "activities": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "timePeriod": "201603010000"
      },
      "products": [
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201603010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "dev",
              "used": [
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            }
          ]
        }
      ]
    },
    {
      "type": "twitter",
      "used": [
        {
          "activities": 84,
          "searchRequests30Day": 4,
          "searchRequestsFullArchive": 0,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "searchRequests30Day": 0,
        "searchRequestsFullArchive": 0,
        "historicalPowertrackDays": 0,
        "historicalPowertrackJobs": 0,
        "timePeriod": "201601010000"
      },
      "products": [
        {
          "type": "Historical PowerTrack 2.0",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 11884,
              "days": 5,
              "jobs": 5
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            }
          ]
        },
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 27456
            },
            {
              "timePeriod": "201601010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 2930
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack 2.0",
              "label": "devel-v2",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 24542
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack 2.0",
              "label": "devel-v2-1",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            }
          ]
        },
        {
          "type": "Search API",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequests30Day": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequests30Day": 0
          },
          "endpoints": [
            {
              "type": "Search API",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequests30Day": 0
              }
            }
          ]
        },
        {
          "type": "Search API (30-Day)",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequests30Day": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequests30Day": 0
          },
          "endpoints": [
            {
              "type": "Search API (30-Day)",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequests30Day": 0
              }
            }
          ]
        },
        {
          "type": "Search API (Full-Archive)",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequestsFullArchive": 0
          },
          "endpoints": [
            {
              "type": "Search API (Full-Archive)",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequestsFullArchive": 0
              }
            }
          ]
        }
      ]
    }
  ]
}

API संदर्भ

get-usage

विधियाँ

Method	Description
GET /metrics/usage/accounts/.json	उपयोग डेटा प्राप्त करें

जहाँ:

• :account_name आपके खाते से संबद्ध (case-sensitive) नाम है, जैसा कि console.gnip.com पर दिखाया जाता है

प्रमाणीकरण और रेट लिमिट

प्रमाणीकरण

Usage API के लिए सभी अनुरोधों में HTTP Basic Authentication आवश्यक है। इसके लिए अपने खाते पर सक्षम किसी भी email/password क्रेडेंशियल्स का उपयोग करें, जिनका इस्तेमाल आप console.gnip.com पर अपने खाते में लॉग इन करने या किसी भी Gnip स्ट्रीम से कनेक्ट करने के लिए करते हैं।

रेट लिमिट

Usage API में प्रति मिनट दो अनुरोधों की सीमा लागू है।

उत्तम प्रथाएँ और सीमाएँ

डेटा उपलब्धता

उपयोग डेटा, संसाधित किए गए डेटा की अंतिम पूर्ण समयावधि (UTC) तक उपभोग की गई डिडुप्लिकेट-हटाई गई गतिविधियों पर आधारित होता है। डेटा आम तौर पर मिनट-दर-मिनट संसाधित और अपडेट किया जाता है, सिवाय उन स्थितियों के जब Gnip सिस्टम परिनियोजित कर रहा हो।

• Usage API आपको 1 मई, 2018 से उपयोग डेटा तक पहुंचने की अनुमति देता है।  1 जुलाई, 2019 के बाद, Usage API आपको पिछले 13 कैलेंडर महीनों का उपयोग डेटा एक्सेस करने की अनुमति देता है। 

• आप fromDate और toDate द्वारा परिभाषित तीन-महीने के अंतरालों में उपयोग डेटा एक्सेस कर सकते हैं

डेटा का अनुरोध करना और प्राप्त करना

Usage API आपके खाते के लिए API endpoint पर HTTP BASIC-AUTH क्रेडेंशियल्स के साथ HTTP GET अनुरोध भेजकर काम करता है।

GET अनुरोध:

अपने उपयोगकर्ता क्रेडेंशियल्स और अकाउंट नाम के साथ नीचे दिए गए endpoint पर एक GET अनुरोध करें:

https://gnip-api.x.com/metrics/usage/accounts/:account_name.json

अतिरिक्त पैरामीटर

bucket	वैकल्पिक। वह समय इकाई जिसके लिए उपयोग डेटा दिया जाएगा। उपयोग डेटा दैनिक या मासिक ग्रैन्युलैरिटी में लौटाया जा सकता है। बिना bucket निर्दिष्ट किए गए अनुरोध मासिक ग्रैन्युलैरिटी लौटाएँगे। विकल्प: ‘month’ या ‘day’
fromDate (YYYYMMDDHHMM)	वैकल्पिक। उपयोग डेटा केवल 1 मई, 2018 से उपलब्ध है। यह सबसे पुराना UTC टाइमस्टैम्प है, जिससे उपयोग डेटा उपलब्ध कराया जाएगा। टाइमस्टैम्प दिन-स्तरीय ग्रैन्युलैरिटी में है और समावेशी है (अर्थात, 201805010000 में 0501 का दिन शामिल है)। जिन अनुरोधों में घंटे और मिनट ग्रैन्युलैरिटी के लिए ‘0000’ के अलावा अन्य मान होते हैं, उन्हें डिफ़ॉल्ट रूप से ‘0000’ कर दिया जाएगा। बिना fromDate या toDate के किए गए अनुरोध वर्तमान महीने का उपयोग डेटा मासिक आधार पर लौटाएँगे और पिछले दो महीनों का ऐतिहासिक संदर्भ भी शामिल करेंगे। कृपया ध्यान दें: 1 जून, 2019 से आप पिछले 13 कैलेंडर महीनों के उपयोग डेटा तक पहुँच सकते हैं। उदाहरण के लिए, अगर तारीख 10 अक्टूबर हो, तो आप पिछले वर्ष की 1 सितंबर तक का उपयोग डेटा देख सकते हैं। उदाहरण: 201810010000, 1 अक्टूबर, 2018 से आगे का डेटा लौटाएगा, जिसमें 1 अक्टूबर भी शामिल होगा।
toDate (YYYYMMDDHHMM)	वैकल्पिक। यह नवीनतम UTC टाइमस्टैम्प है, जिस तक उपयोग डेटा उपलब्ध कराया जाएगा। टाइमस्टैम्प दिन-स्तरीय ग्रैन्युलैरिटी में है और समावेशी नहीं है (अर्थात, 201703020000 में 0302 दिन का डेटा शामिल नहीं है)। जब वर्तमान दिन या भविष्य की किसी तारीख के लिए toDate निर्दिष्ट किया जाता है, तो उपयोग डेटा अंतिम पूर्ण दिन (UTC) तक लौटाया जाएगा। जिन अनुरोधों में घंटे और मिनट ग्रैन्युलैरिटी के लिए ‘0000’ के अलावा अन्य मान होते हैं, उन्हें डिफ़ॉल्ट रूप से ‘0000’ कर दिया जाएगा। बिना toDate वाला अनुरोध अगले bucket पर डिफ़ॉल्ट होगा (bucket=day के लिए कल और bucket=month के लिए अगला महीना)। बिना fromDate और toDate के किया गया अनुरोध bucket=month पर डिफ़ॉल्ट होगा और वर्तमान महीने के साथ उससे ठीक पहले के दो महीनों का डेटा दिखाएगा। उदाहरण: 201703050000, 5 मार्च, 2017 तक का डेटा लौटाएगा, जिसमें 5 मार्च का कोई भी डेटा शामिल नहीं होगा।

उदाहरण GET अनुरोध

यह अनुरोध 1 मार्च, 2017 से 5 मार्च, 2017 तक मासिक ग्रैन्युलैरिटी में डेटा लौटाएगा, जिसमें 5 मार्च, 2017 का कोई भी डेटा शामिल नहीं होगा।

curl -u “https://gnip-api.x.com/metrics/usage/accounts/:account_name.json?bucket=month&fromdate=201403010000&toDate=201403150000”

डेटा प्रारूप

नीचे दी गई तालिकाएँ Usage API से लौटाए गए उपयोग डेटा की रूट-लेवल डेटा संरचनाओं का वर्णन करती हैं। जिन फ़ील्ड्स में उप-फ़ील्ड्स के कई स्तर हैं, उनके लिए उप-फ़ील्ड्स का विवरण देखने हेतु दिए गए लिंक पर क्लिक करें।

यदि आप पूर्ण Usage API पेलोड का एक नमूना देखना चाहते हैं, तो कृपया इस पृष्ठ पर जाएँ।

account	वह ऑब्जेक्ट जो उस खाते को दर्शाता है जिसके लिए उपयोग डेटा का अनुरोध किया गया था।
bucket	समय की वह इकाई जिसके लिए उपयोग डेटा उपलब्ध कराया जाता है। यह ‘day’ या ‘month’ में से कोई एक हो सकती है।
fromDate	सबसे प्रारंभिक UTC timestamp, जिससे आप उपयोग डेटा प्राप्त करना चाहते हैं (शामिल)।
toDate	सबसे नवीनतम UTC timestamp, जिससे आप उपयोग डेटा प्राप्त करना चाहते हैं (शामिल नहीं)।
publishers	इसमें तीन मुख्य ऑब्जेक्ट शामिल हैं: Used, projected, और products।