GET /v1/recap | Τεκμηρίωση REST API NowMetrix

Αίτημα

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

Χρησιμοποιήστε το Recap όταν η ενσωμάτωσή σας χρειάζεται αναδρομή σε προηγούμενα δεδομένα: ιστορικές αναφορές, εξαγωγές κορυφαίων σελίδων, προσαρμοσμένα χρονικά διαστήματα ή αποτελέσματα φιλτραρισμένα με αναζήτηση.

Έλεγχος ταυτότητας

Απαιτείται κλειδί API στην κεφαλίδα Authorization: Authorization: Bearer nm_YOUR_KEY.

Παράμετροι ερωτήματος

Όνομα	Τύπος	Υποχρεωτική	Περιγραφή
`site`	`string`	υποχρεωτική	Tracker ID. Το κλειδί API πρέπει να έχει πρόσβαση σε αυτό το tracker.
`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. Για τις επόμενες σελίδες απαιτείται `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, η υπάρχουσα μορφή απόκρισης και το όριο παραμένουν αμετάβλητα.

Για κάθε επόμενη σελίδα, στείλτε το pagination.next_offset ως offset και το pagination.snapshot_id ως snapshot. Επαναλάβετε τις αρχικές παραμέτρους site, preset, start, end και search, συμπεριλαμβανομένων των προσαρμοσμένων ημερομηνιών. Διακόψτε όταν το next_offset είναι null. Offset ίσο ή μεγαλύτερο από τον διαθέσιμο αριθμό επιστρέφει κενό πίνακα top_pages.

Η σειρά των άρθρων, οι προβολές σελίδας, οι ημερήσιες τιμές, η σύνοψη και το generated_at παραμένουν σταθερά σε όλες τις σελίδες, ακόμη και σε διαστήματα που περιλαμβάνουν τη σημερινή ημέρα. Οι συνοπτικές μετρήσεις καλύπτουν ολόκληρο το επιλεγμένο διάστημα· το pagination.total μετρά μόνο τα άρθρα του περιορισμένου snapshot. Κάθε αίτημα εξακολουθεί να απαιτεί έγκυρη εξουσιοδότηση και συνυπολογίζεται στο όριο αιτημάτων του tracker.

Τα snapshot λήγουν μετά από 10 λεπτά, χωρίς ανανέωση κατά την ανάγνωση. Σε HTTP 410, απορρίψτε την ημιτελή περιήγηση και ξεκινήστε ξανά με offset=0 χωρίς snapshot. Τα παρακάτω παραδείγματα δείχνουν το πρώτο αίτημα, μια συνέχεια και το πρόσθετο αντικείμενο σελιδοποίησης.

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`	Το Tracker ID που χρησιμοποιήθηκε στο αίτημα.
`preset`	`string`	Το preset που προσδιορίστηκε και χρησιμοποιήθηκε για την απόκριση.
`timezone`	`string`	Η ζώνη ώρας του tracker που χρησιμοποιήθηκε για τον προσδιορισμό των τοπικών ημερομηνιών.
`range`	`object`	Το χρονικό διάστημα που προσδιορίστηκε, με from, to, label και αριθμό ημερών.
`limits`	`object`	Τα διαθέσιμα όρια ιστορικού για το tracker.
`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`	Μη αναγνώσιμο ID για επόμενα αιτήματα που χρησιμοποιούν την παράμετρο snapshot. Συνδέεται με τον ταυτοποιημένο χρήστη και το tracker.
`pagination.expires_at`	`string`	Σταθερός χρόνος λήξης σε UTC, 10 λεπτά μετά την αποθήκευση. Η ανάγνωση σελίδων δεν παρατείνει τη διάρκεια.

Επικαιρότητα και προσωρινή αποθήκευση

Τα αιτήματα χωρίς σελιδοποίηση χρησιμοποιούν την υπάρχουσα βραχυχρόνια προσωρινή μνήμη (microcache) των 60 δευτερολέπτων και την εφεδρική ιστορική πηγή. Η σελιδοποίηση αποθηκεύει ένα αμετάβλητο snapshot στο τοπικό Stats Redis για 600 δευτερόλεπτα, με αυτόματη λήξη και χωρίς κυλιόμενη ανανέωση. Πανομοιότυπα αρχικά αιτήματα από τον ίδιο χρήστη εντός 60 δευτερολέπτων μπορούν να επαναχρησιμοποιήσουν ένα snapshot, επομένως χρησιμοποιήστε το expires_at ως προθεσμία. Οι συνέχειες δεν δημιουργούν ξανά τα δεδομένα και δεν χρησιμοποιούν διαφορετικό snapshot ως εφεδρική λύση.

Σφάλματα

HTTP	Κωδικός	Περιγραφή
400	`site_required`	Λείπει η υποχρεωτική παράμετρος site.
401	`missing_token`	Λείπει η κεφαλίδα Authorization.
401	`invalid_token`	Το token δεν είναι έγκυρο ή έχει ανακληθεί.
403	`site_not_authorized`	Το κλειδί API δεν έχει πρόσβαση σε αυτό το tracker.
429	`rate_limit_exceeded`	Έχει γίνει υπέρβαση του ορίου αιτημάτων.
503	`redis_unavailable`	Το backend πραγματικού χρόνου δεν είναι προσωρινά διαθέσιμο.
503	`clickhouse_unavailable`	Τα ιστορικά δεδομένα δεν είναι προσωρινά διαθέσιμα.
500	`encoding_failed`	Δεν ήταν δυνατή η κωδικοποίηση της απόκρισης Recap.
400	`invalid_pagination`	Οι παράμετροι ερωτήματος σελιδοποίησης πρέπει να είναι απλές τιμές.
400	`invalid_offset`	Το offset πρέπει να είναι ακέραιος από 0 έως 2000.
400	`invalid_snapshot`	Το ID του snapshot έχει μη έγκυρη μορφή.
400	`snapshot_required`	Τα offset μεγαλύτερα του μηδενός απαιτούν ID snapshot. Ξεκινήστε με offset=0.
400	`snapshot_mismatch`	Το preset, οι ημερομηνίες ή η αναζήτηση διαφέρουν από το αρχικό αίτημα.
410	`snapshot_expired`	Το snapshot έληξε ή δεν είναι πλέον διαθέσιμο σε αυτό το πλαίσιο χρήστη/tracker. Ξεκινήστε ξανά με offset=0 και χωρίς snapshot.
503	`snapshot_storage_unavailable`	Δεν είναι δυνατή η ανάγνωση ή η εγγραφή στον χώρο αποθήκευσης snapshot. Δοκιμάστε ξανά· ένα υπάρχον ID snapshot πρέπει να παραμείνει αμετάβλητο.
503	`recap_unavailable`	Δεν είναι δυνατή προς το παρόν η δημιουργία πλήρους νέου snapshot. Δοκιμάστε ξανά σύντομα.

{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}