REST API एंडपॉइंट

GET /v1/recap

प्रीसेट या कस्टम तारीख सीमा के लिए Recap डेटा, सारांश मेट्रिक्स और शीर्ष पेज।

रिक्वेस्ट

GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=25

जब आपके इंटीग्रेशन को पिछली अवधि का डेटा चाहिए, तब Recap का उपयोग करें—जैसे ऐतिहासिक रिपोर्टिंग, शीर्ष पेजों का एक्सपोर्ट, कस्टम तारीख सीमाएँ या खोज से फ़िल्टर किए गए परिणाम।

ऑथेंटिकेशन

Authorization हेडर में API कुंजी देना आवश्यक है: Authorization: Bearer nm_YOUR_KEY.

क्वेरी पैरामीटर

नाम प्रकार आवश्यक विवरण
site string आवश्यक ट्रैकर ID। API कुंजी को इस ट्रैकर का ऐक्सेस होना चाहिए।
preset string वैकल्पिक तारीख का प्रीसेट। इनमें से एक चुनें: today, yesterday, last7, last14, last30, last90, this_month, last_month, all_time, custom। डिफ़ॉल्ट: last30।
start date वैकल्पिक preset=custom के लिए शुरुआती तारीख। फ़ॉर्मैट: YYYY-MM-DD।
end date वैकल्पिक preset=custom के लिए अंतिम तारीख। फ़ॉर्मैट: YYYY-MM-DD।
limit integer वैकल्पिक पेजिनेशन वाले रिस्पॉन्स सहित, हर रिस्पॉन्स में शीर्ष पेजों की अधिकतम संख्या। मान 1–100 के बीच सीमित किए जाते हैं। डिफ़ॉल्ट: 100।
q string वैकल्पिक शीर्ष पेजों के लिए खोज शब्द। URL, शीर्षक या लेखक से मिलान करता है। उपनाम: search।
search string वैकल्पिक q का उपनाम।
offset integer वैकल्पिक offset=0 से पेजिनेशन शुरू करें। मान 0 से 2000 तक का integer होना चाहिए। बाद के पेजों के लिए snapshot आवश्यक है। offset या snapshot के बिना मौजूदा रिस्पॉन्स में कोई बदलाव नहीं होता।
snapshot string वैकल्पिक पहले रिस्पॉन्स से pagination.snapshot_id का उपयोग करें। मूल site, preset, start, end और search पैरामीटर दोहराएँ। पेज का आकार बदला जा सकता है। नए सिरे से सभी पेज प्राप्त करने के लिए snapshot पैरामीटर हटा दें।

cURL का उदाहरण

curl -H "Authorization: Bearer nm_YOUR_KEY" \
  "https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=25"

रिस्पॉन्स का उदाहरण

{
  "site": "TRACKER_ID",
  "preset": "last30",
  "timezone": "Europe/Zurich",
  "range": {
    "from": "2026-05-28",
    "to": "2026-06-26",
    "label": "Last 30 Days",
    "days": 30
  },
  "limits": {
    "min_date": "2025-03-17",
    "max_date": "2026-06-26",
    "max_days": null
  },
  "search": {
    "query": ""
  },
  "daily": [
    {
      "date": "2026-06-25",
      "pageviews": 102400,
      "visits": 12800
    },
    {
      "date": "2026-06-26",
      "pageviews": 98450,
      "visits": 12130
    }
  ],
  "summary": {
    "total_pageviews": 3158127,
    "total_visits": 388450,
    "pages_per_visitor": 8.1
  },
  "top_pages": [
    {
      "rank": 1,
      "title": "Home page",
      "author": "",
      "pubdate": "",
      "url": "/",
      "url_full": "https://example-media.test/",
      "url_id": "5dc0a5883395e2a126e5239650d9268e",
      "thumbnail": "https://realtimemetadata.fra1.cdn.digitaloceanspaces.com/thumbnails/example.jpg",
      "pageviews": 159280
    },
    {
      "rank": 2,
      "title": "Culture desk live notes",
      "author": "Alex Morgan",
      "pubdate": "2026-06-24",
      "url": "/culture/live-notes",
      "url_full": "https://example-media.test/culture/live-notes",
      "url_id": "b35c1a5f2fd0cbb7f3c13b853c2a9d2c",
      "thumbnail": "https://realtimemetadata.fra1.cdn.digitaloceanspaces.com/thumbnails/example-2.jpg",
      "pageviews": 85632
    }
  ],
  "generated_at": "2026-06-26T12:30:00Z"
}

पेजिनेशन

पेजिनेशन शुरू करने के लिए offset=0 जोड़ें। हर रिस्पॉन्स में अधिकतम 100 लेख होते हैं; snapshot में अधिकतम 2000 लेख होते हैं। offset या snapshot के बिना मौजूदा रिस्पॉन्स फ़ॉर्मैट और limit में कोई बदलाव नहीं होता।

हर अगले पेज के लिए pagination.next_offset को offset और pagination.snapshot_id को snapshot के रूप में भेजें। मूल site, preset, start, end और search पैरामीटर दोहराएँ, जिनमें कस्टम तारीखें भी शामिल हैं। जब next_offset null हो जाए, तब रुकें। उपलब्ध संख्या के बराबर या उससे अधिक offset होने पर खाली top_pages ऐरे मिलता है।

पेजों के बीच लेखों का क्रम, पेजव्यू, दैनिक मान, summary और generated_at एक जैसे रहते हैं; इसमें आज की तारीख वाली रेंज भी शामिल हैं। सारांश मेट्रिक्स पूरी चुनी गई अवधि को कवर करते हैं; pagination.total केवल सीमित snapshot में मौजूद लेखों की संख्या गिनता है। हर रिक्वेस्ट के लिए अब भी मान्य प्राधिकरण आवश्यक है और वह ट्रैकर की अनुरोध सीमा में गिनी जाती है।

स्नैपशॉट 10 मिनट बाद समाप्त हो जाते हैं। उन्हें पढ़ने से यह समयसीमा कभी नहीं बढ़ती। HTTP 410 मिलने पर पिछले अधूरे परिणाम छोड़ दें और snapshot के बिना offset=0 से फिर शुरू करें। नीचे दिए गए उदाहरणों में पहली रिक्वेस्ट, उसका अगला पेज और अतिरिक्त pagination ऑब्जेक्ट दिखाया गया है।

GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=100&offset=0
GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=100&offset=100&snapshot=0123456789abcdef0123456789abcdef0123456789abcdef
{
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2000,
    "max_results": 2000,
    "has_more": true,
    "next_offset": 100,
    "snapshot_id": "0123456789abcdef0123456789abcdef0123456789abcdef",
    "expires_at": "2026-06-26T12:40:00Z"
  }
}

रिस्पॉन्स फ़ील्ड

फ़ील्ड प्रकार विवरण
site string रिक्वेस्ट के लिए उपयोग किया गया ट्रैकर ID।
preset string रिस्पॉन्स के लिए उपयोग किया गया निर्धारित प्रीसेट।
timezone string स्थानीय तारीखें निर्धारित करने के लिए उपयोग किया गया ट्रैकर का समय क्षेत्र।
range object निर्धारित तारीख सीमा, जिसमें from, to, label और दिनों की संख्या होती है।
limits object ट्रैकर के लिए उपलब्ध ऐतिहासिक डेटा की सीमाएँ।
search.query string शीर्ष पेजों को फ़िल्टर करने के लिए उपयोग की गई सामान्यीकृत खोज क्वेरी।
daily[] array<object> निर्धारित तारीख सीमा के लिए हर दिन के पेजव्यू और विज़िट।
summary.total_pageviews integer निर्धारित तारीख सीमा में कुल पेजव्यू।
summary.total_visits integer निर्धारित तारीख सीमा में कुल विज़िट।
summary.pages_per_visitor number पेजव्यू को विज़िट से भाग देने पर प्राप्त मान, एक दशमलव तक राउंड किया गया।
top_pages[] array<object> पेजव्यू के आधार पर क्रमबद्ध शीर्ष पेज।
top_pages[].rank integer पेजिनेशन के दौरान पूरे snapshot में रैंक; रैंक अगले पेजों पर भी जारी रहती है।
top_pages[].title string पेज का शीर्षक।
top_pages[].author string उपलब्ध होने पर लेखक।
top_pages[].pubdate string उपलब्ध होने पर प्रकाशन की तारीख।
top_pages[].url string पाथ या संक्षिप्त URL।
top_pages[].url_full string उपलब्ध होने पर पूर्ण URL।
top_pages[].url_id string स्थिर URL पहचानकर्ता।
top_pages[].thumbnail string उपलब्ध होने पर थंबनेल URL।
top_pages[].pageviews integer निर्धारित तारीख सीमा के पेजव्यू।
generated_at string डेटा तैयार किए जाने का UTC टाइमस्टैम्प।
pagination object केवल पेजिनेशन मोड में मौजूद होता है। सभी पेजों में कुल अधिकतम 2000 लेख उपलब्ध होते हैं।
pagination.limit integer प्रभावी पेज आकार, 1 से 100 तक।
pagination.offset integer माँगे गए पेज की शून्य-आधारित स्थिति।
pagination.total integer इस snapshot में लेखों की संख्या, जो अधिकतम 2000 तक सीमित है। यह मेल खाने वाले सभी URL की असीमित कुल संख्या नहीं है।
pagination.max_results integer हर snapshot में लेखों की अधिकतम संख्या: 2000।
pagination.has_more boolean क्या इस snapshot में कोई और पेज उपलब्ध है।
pagination.next_offset integer|null अगले पेज के लिए इस मान को offset के रूप में भेजें। Null का अर्थ है कि अंत पहुँच गया है।
pagination.snapshot_id string snapshot पैरामीटर का उपयोग करने वाली अगली रिक्वेस्ट के लिए अपारदर्शी ID। यह प्रमाणित उपयोगकर्ता और ट्रैकर से संबद्ध होता है।
pagination.expires_at string UTC में निश्चित समाप्ति समय, स्टोरेज के 10 मिनट बाद। पेज पढ़ने से इसकी अवधि नहीं बढ़ती।

डेटा की ताज़गी और कैशिंग

पेजिनेशन के बिना रिक्वेस्ट मौजूदा 60-सेकंड माइक्रोकैश और ऐतिहासिक फ़ॉलबैक का उपयोग करती हैं। पेजिनेशन स्थानीय Stats Redis में 600 सेकंड के लिए अपरिवर्तनीय snapshot सहेजता है; यह अपने-आप समाप्त होता है और इसकी अवधि आगे नहीं बढ़ती। 60 सेकंड के भीतर उसी उपयोगकर्ता द्वारा की गई एक जैसी शुरुआती रिक्वेस्ट किसी snapshot का फिर से उपयोग कर सकती हैं, इसलिए समयसीमा के लिए expires_at का उपयोग करें। अगले पेजों की रिक्वेस्ट कभी डेटा को फिर से तैयार नहीं करतीं और फ़ॉलबैक के रूप में किसी दूसरे snapshot का उपयोग नहीं करतीं।

त्रुटियाँ

HTTP कोड विवरण
400 site_required आवश्यक site पैरामीटर मौजूद नहीं है।
401 missing_token Authorization हेडर मौजूद नहीं है।
401 invalid_token टोकन अमान्य है या रद्द किया जा चुका है।
403 site_not_authorized API कुंजी को इस ट्रैकर का ऐक्सेस नहीं है।
429 rate_limit_exceeded अनुरोधों की निर्धारित सीमा पार हो गई है।
503 redis_unavailable रीयलटाइम बैकएंड अस्थायी रूप से उपलब्ध नहीं है।
503 clickhouse_unavailable ऐतिहासिक डेटा अस्थायी रूप से उपलब्ध नहीं है।
500 encoding_failed Recap रिस्पॉन्स को एन्कोड नहीं किया जा सका।
400 invalid_pagination पेजिनेशन क्वेरी पैरामीटर एकल मान होने चाहिए।
400 invalid_offset offset का मान 0 से 2000 तक की पूर्ण संख्या होना चाहिए।
400 invalid_snapshot स्नैपशॉट ID का फ़ॉर्मैट अमान्य है।
400 snapshot_required शून्य से अधिक offset के लिए snapshot ID आवश्यक है। offset=0 से शुरू करें।
400 snapshot_mismatch प्रीसेट, तारीखें या search मूल रिक्वेस्ट से अलग हैं।
410 snapshot_expired स्नैपशॉट की अवधि समाप्त हो गई है या यह इस उपयोगकर्ता/ट्रैकर संदर्भ में उपलब्ध नहीं है। offset=0 और snapshot के बिना फिर शुरू करें।
503 snapshot_storage_unavailable स्नैपशॉट के भंडारण से डेटा पढ़ा या उसमें लिखा नहीं जा सकता। फिर प्रयास करें; मौजूदा snapshot ID में बदलाव नहीं होना चाहिए।
503 recap_unavailable इस समय नया पूरा snapshot नहीं बनाया जा सकता। थोड़ी देर बाद फिर प्रयास करें। 
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}