CrUX इतिहास एपीआई को इस्तेमाल करने का तरीका

Johannes Henkel

Jasmine Yan

Barry Pollard

पब्लिश करने की तारीख: 7 फ़रवरी, 2023, पिछली बार अपडेट करने की तारीख: 11 अप्रैल, 2025

इस गाइड में, Chrome UX Report (CrUX) History API एंडपॉइंट के बारे में बताया गया है. यह एंडपॉइंट, वेब परफ़ॉर्मेंस के डेटा की टाइम सीरीज़ उपलब्ध कराता है. यह डेटा हर हफ़्ते अपडेट होता है. इससे आपको छह महीने तक का इतिहास देखने को मिलता है. इसमें 40 डेटा पॉइंट होते हैं, जो एक हफ़्ते के अंतराल पर होते हैं.

CrUX API के ओरिजनल एंडपॉइंट से मिलने वाले रोज़ाना के अपडेट के साथ इसका इस्तेमाल करने पर, अब आपको हाल ही का डेटा और पहले क्या हुआ, दोनों की जानकारी तुरंत मिल सकती है. इससे यह समय के साथ वेब पेज में होने वाले बदलावों को देखने के लिए एक बेहतरीन टूल बन जाता है.

इस पेज पर मौजूद एपीआई को आज़माएं

इसे आज़माएं!

CrUX API से हर दिन क्वेरी करना

CrUX API के बारे में पिछले लेख में दी गई जानकारी के मुताबिक, किसी खास ऑरिजिन के लिए फ़ील्ड डेटा का स्नैपशॉट इस तरह से पाया जा सकता है:

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [{
          "start": 0, "end": 2500, "density": 0.9192
        }, {
          "start": 2500, "end": 4000, "density": 0.0513
        }, {
          "start": 4000, "density": 0.0294
        }],
        "percentiles": {
          "p75": 1303
        }
      }
      // ...
    },
    "collectionPeriod": {
      "firstDate": { "year": 2022, "month": 12, "day": 27 },
      "lastDate": { "year": 2023, "month": 1, "day": 23 }
    }
  }
}

इस स्नैपशॉट में, 28 दिनों के कलेक्शन की अवधि के लिए हिस्टोग्राम डेंसिटी वैल्यू और पर्सेंटाइल वैल्यू शामिल हैं. इस मामले में, यह अवधि 27 दिसंबर, 2022 से 23 जनवरी, 2023 तक है.

CrUX History API में क्वेरी करना

इतिहास वाले एंडपॉइंट को कॉल करने के लिए, यूआरएल में मौजूद queryRecord को curl कमांड में queryHistoryRecord से बदलें. पिछले कॉल के लिए इस्तेमाल की गई CrUX API कुंजी का इस्तेमाल करने से काम हो जाएगा. collectionPeriodCount से, दिखाई जाने वाली टाइम सीरीज़ की एंट्री की संख्या तय की जाती है. ज़्यादा से ज़्यादा 40 एंट्री दिखाई जा सकती हैं. अगर कोई वैल्यू नहीं दी गई है, तो डिफ़ॉल्ट रूप से यह 25 पर सेट होता है.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'

जवाब का फ़ॉर्मैट एक जैसा है, लेकिन इसमें ज़्यादा डेटा है! अब एक डेटा पॉइंट के बजाय, 75वें पर्सेंटाइल (p75) और हिस्टोग्राम डेंसिटी वैल्यू वाले फ़ील्ड के लिए टाइम सीरीज़ मौजूद हैं.

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377
          ]
        }
      }
      // ...
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]
  }
}

इस उदाहरण में, सबसे बड़े कॉन्टेंटफ़ुल पेंट (एलसीपी) मेट्रिक के 0 से 2500 मि॰से॰ वाले बकेट के लिए densities टाइम सीरीज़ [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. है. इनमें से हर डेंसिटी को, इससे जुड़ी collectionPeriods एंट्री के दौरान देखा गया था. उदाहरण के लिए, पांचवीं डेंसिटी 0.9183, कलेक्शन की पांचवीं अवधि की डेंसिटी थी. यह अवधि 3 सितंबर, 2022 को खत्म हुई थी. इसके बाद, 0.9187 डेंसिटी, उस हफ़्ते के आखिर में खत्म हुई अवधि की डेंसिटी थी.

दूसरे शब्दों में कहें, तो https://web.dev के उदाहरण में, टाइम सीरीज़ की आखिरी एंट्री की व्याख्या करने पर पता चला कि 14 अगस्त, 2022 से 10 सितंबर, 2022 तक, 91.87% पेज लोड में एलसीपी की वैल्यू 2500 मि॰से॰ से कम थी, 5.27% में 2500 मि॰से॰ से 4000 मि॰से॰ के बीच थी, और 2.85% में 4000 मि॰से॰ से ज़्यादा थी.

इसी तरह, p75 वैल्यू के लिए एक टाइम सीरीज़ है: 14 अगस्त, 2022 से 10 सितंबर, 2022 तक एलसीपी p75 1377 था. इसका मतलब है कि इस कलेक्शन पीरियड के दौरान, 75% उपयोगकर्ताओं को 1,377 मि॰से॰ से कम एलसीपी मिला. वहीं, 25% उपयोगकर्ताओं को 1,377 मि॰से॰ से ज़्यादा एलसीपी मिला.

उदाहरण में, सिर्फ़ छह टाइम सीरीज़ एंट्री और कलेक्शन की अवधि दी गई है. हालांकि, एपीआई से मिलने वाले जवाबों में डिफ़ॉल्ट रूप से 25 टाइम सीरीज़ एंट्री होती हैं. साथ ही, अनुरोध में "collectionPeriodCount": 40 के बारे में जानकारी देने पर, ज़्यादा से ज़्यादा 40 एंट्री मिलती हैं. इन सभी कलेक्शन पीरियड की आखिरी तारीखें शनिवार हैं. इनके बीच सात दिनों का अंतर है. "collectionPeriodCount": 40 इस हिसाब से, यह 10 महीने का कलेक्शन पीरियड है.

ध्यान दें: रोज़ के एपीआई के उलट, CrUX History API को सिर्फ़ सोमवार को अपडेट किया जाता है. इसमें पिछले शनिवार तक का डेटा शामिल होता है. हालांकि, रोज़ाना के एपीआई की तरह, CrUX History API में हर वैल्यू को पिछले 28 दिनों के हिसाब से मेज़र किया जाता है. इसका मतलब है कि History API को, उस तारीख के लिए वही डेटा दिखाना चाहिए जो Daily API का इस्तेमाल करके उपलब्ध था. अब इसे सिर्फ़ पिछली तारीखों के हिसाब से क्वेरी किया जा सकता है. हालांकि, इसका मतलब यह है कि History API में डेटा की ओवरलैपिंग वाली अवधियां शामिल होती हैं. हालांकि, रुझान के विश्लेषण के तौर पर, समय के साथ-साथ मेट्रिक में होने वाले बदलाव को ट्रैक करना फ़ायदेमंद होता है.

किसी भी जवाब में, हिस्टोग्राम बिन डेंसिटी और p75 वैल्यू के लिए टाइम सीरीज़ की लंबाई, collectionPeriods फ़ील्ड में मौजूद ऐरे की लंबाई के बराबर होगी: इन ऐरे में इंडेक्स के आधार पर एक-से-एक का कॉरेस्पोंडेंस होता है.

पेज-लेवल का डेटा क्वेरी करना

CrUX History API, ऑरिजिन-लेवल के डेटा के साथ-साथ, पेज-लेवल के पुराने डेटा को भी ऐक्सेस करने की अनुमति देता है. हालांकि, ऑरिजिन-लेवल का डेटा पहले भी BigQuery पर CrUX डेटासेट का इस्तेमाल करके उपलब्ध था. हालांकि, पेज-लेवल का पुराना डेटा सिर्फ़ तब उपलब्ध होता था, जब साइटें खुद डेटा इकट्ठा और सेव करती थीं. नया एपीआई अब पेज-लेवल के उस पुराने डेटा को अनलॉक करता है.

पेज-लेवल के डेटा के लिए भी इसी तरह क्वेरी की जा सकती है. हालांकि, पेलोड में origin के बजाय url का इस्तेमाल किया जाता है:

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"url": "https://web.dev/blog/"}'

पेज-लेवल (और ऑरिजिन-लेवल) के पुराने डेटा के लिए, ज़रूरी शर्तें वही होती हैं जो CrUX के बाकी डेटा के लिए होती हैं. इसलिए, ऐसा हो सकता है कि कुछ पेजों का पूरा पुराना रिकॉर्ड न हो. ऐसे मामलों में, "मौजूद नहीं" डेटा को histogramTimeseries के लिए "NaN" और percentilesTimeseries के लिए null से दिखाया जाएगा. अंतर की वजह यह है कि हिस्टोग्राम डेंसिटी हमेशा संख्याएं होती हैं, जबकि पर्सेंटाइल संख्याएं या स्ट्रिंग हो सकती हैं. सीएलएस, स्ट्रिंग का इस्तेमाल करता है. भले ही, वे संख्याओं की तरह दिखती हों.

डेटा को विज़ुअलाइज़ करना

डेटा को विज़ुअलाइज़ करने का सबसे आसान तरीका, CrUX Vis का इस्तेमाल करना है. यह टूल खास तौर पर, CrUX History API की क्षमताओं को दिखाने के लिए बनाया गया है. ज़्यादा जानकारी के लिए, CrUX Vis का दस्तावेज़ पढ़ें.

मिलते-जुलते चार्ट खुद जनरेट करने के लिए, हमने एक उदाहरण Colab बनाया है. Colab या 'Colaboratory' की मदद से, अपने ब्राउज़र में Python कोड लिखा और उसे एक्ज़ीक्यूट किया जा सकता है. CrUX History API Colab (source) में, API को कॉल करने और डेटा को चार्ट में दिखाने के लिए Python का इस्तेमाल किया जाता है.

इस Colab की मदद से, छोटा सा फ़ॉर्म भरकर ये काम किए जा सकते हैं: p75 चार्ट बनाना, ट्राइ-बिन चार्ट बनाना, टेबल के फ़ॉर्मैट में डेटा पाना, और CrUX API के लिए अनुरोध और जवाब का पेयर देखना. इस सुविधा का इस्तेमाल करने के लिए, आपको प्रोग्रामर होने की ज़रूरत नहीं है. हालांकि, आपके पास Python कोड को देखने और उसे बेहतर बनाने का विकल्प होता है! कृपया इसका इस्तेमाल करें और हमें बताएं कि आपको यह सुविधा कैसी लगी!

ज़रूरी नहीं है कि आप सिर्फ़ Colab या Python का इस्तेमाल करें. यह इस नए एपीआई को इस्तेमाल करने का सिर्फ़ एक उदाहरण है. JSON पर आधारित एचटीटीपी एंडपॉइंट होने की वजह से, एपीआई को किसी भी टेक्नोलॉजी से क्वेरी किया जा सकता है.

नतीजा

CrUX History API एंडपॉइंट के लॉन्च होने से पहले, साइट के मालिकों को CrUX से सिर्फ़ सीमित पुरानी जानकारी मिलती थी. BigQuery का इस्तेमाल करके, हर महीने के हिसाब से ऑरिजिन-लेवल का डेटा उपलब्ध था. हालांकि, हफ़्ते के हिसाब से डेटा उपलब्ध नहीं था. साथ ही, पेज-लेवल का पुराना डेटा भी उपलब्ध नहीं था. साइट के मालिक, रोज़ाना के एपीआई का इस्तेमाल करके इस डेटा को खुद रिकॉर्ड कर सकते हैं. हालांकि, अक्सर इसकी ज़रूरत तब ही पड़ती है, जब मेट्रिक में गिरावट आ जाती है.

CrUX History API को लॉन्च करने का मकसद यह है कि इससे साइट के मालिकों को, साइट की मेट्रिक में होने वाले बदलावों को बेहतर तरीके से समझने में मदद मिलेगी. साथ ही, यह समस्याओं के होने पर डाइग्नोस्टिक टूल के तौर पर काम करेगा. अगर नए एपीआई का इस्तेमाल किया जा रहा है, तो Chrome UX Report (Discussions) Google ग्रुप पर सुझाव/राय दें या शिकायत करें.

Acknowledgements

Unsplash पर डेव हेरिंग की हीरो इमेज