Endpoint REST API

GET /v1/recap

Data Recap, metrik ringkasan, dan halaman teratas untuk preset atau rentang tanggal khusus.

Permintaan

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

Gunakan Recap saat integrasi Anda perlu melihat data historis: pelaporan historis, ekspor halaman teratas, rentang tanggal khusus, atau hasil yang difilter berdasarkan pencarian.

Autentikasi

Memerlukan kunci API dalam header Authorization: Authorization: Bearer nm_YOUR_KEY.

Parameter kueri

Nama Tipe Wajib Deskripsi
site string wajib ID tracker. Kunci API harus memiliki akses ke tracker ini.
preset string opsional Preset tanggal. Salah satu dari today, yesterday, last7, last14, last30, last90, this_month, last_month, all_time, custom. Default: last30.
start date opsional Tanggal mulai untuk preset=custom. Format: YYYY-MM-DD.
end date opsional Tanggal akhir untuk preset=custom. Format: YYYY-MM-DD.
limit integer opsional Jumlah maksimum halaman teratas per respons, termasuk respons berpaginasi. Nilai dibatasi dalam rentang 1–100. Default: 100.
q string opsional Istilah pencarian untuk halaman teratas. Mencocokkan URL, judul, atau penulis. Alias: search.
search string opsional Alias untuk q.
offset integer opsional Aktifkan paginasi dengan offset=0. Bilangan bulat dari 0 hingga 2000. Halaman berikutnya memerlukan snapshot. Tanpa offset atau snapshot, respons yang ada tetap tidak berubah.
snapshot string opsional Gunakan pagination.snapshot_id dari respons pertama. Ulangi parameter site, preset, start, end, dan search asli. Ukuran halaman dapat berubah. Hilangkan snapshot untuk memulai penelusuran baru.

Contoh cURL

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

Contoh respons

{
  "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"
}

Paginasi

Tambahkan offset=0 untuk mengaktifkan paginasi. Setiap respons memuat paling banyak 100 artikel; snapshot memuat paling banyak 2000 artikel. Tanpa offset atau snapshot, format respons dan limit yang ada tetap tidak berubah.

Untuk setiap halaman berikutnya, kirim pagination.next_offset sebagai offset dan pagination.snapshot_id sebagai snapshot. Ulangi parameter site, preset, start, end, dan search asli, termasuk tanggal khusus. Hentikan proses saat next_offset bernilai null. Offset yang sama dengan atau melebihi jumlah data yang tersedia akan menghasilkan array top_pages kosong.

Urutan artikel, pageviews, nilai harian, summary, dan generated_at tetap sama di semua halaman, termasuk rentang yang mencakup hari ini. Metrik ringkasan mencakup seluruh rentang yang dipilih; pagination.total hanya menghitung artikel dalam snapshot yang jumlahnya dibatasi. Setiap permintaan tetap memerlukan autentikasi yang valid dan diperhitungkan dalam rate limit tracker.

Snapshot kedaluwarsa setelah 10 menit tanpa perpanjangan saat dibaca. Jika menerima HTTP 410, buang penelusuran parsial dan mulai ulang dengan offset=0 tanpa snapshot. Contoh berikut menunjukkan permintaan pertama, permintaan lanjutan, dan objek pagination tambahan.

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"
  }
}

Kolom respons

Kolom Tipe Deskripsi
site string ID tracker yang digunakan untuk permintaan.
preset string Preset hasil resolusi yang digunakan untuk respons.
timezone string Zona waktu tracker yang digunakan untuk menentukan tanggal lokal.
range object Rentang tanggal yang ditetapkan, dengan from, to, label, dan jumlah hari.
limits object Batas riwayat yang tersedia untuk tracker.
search.query string Kueri pencarian yang dinormalisasi dan digunakan untuk memfilter halaman teratas.
daily[] array<object> Pageviews dan kunjungan harian untuk rentang hasil resolusi.
summary.total_pageviews integer Total pageviews di seluruh rentang hasil resolusi.
summary.total_visits integer Total kunjungan di seluruh rentang hasil resolusi.
summary.pages_per_visitor number Pageviews dibagi jumlah kunjungan, dibulatkan menjadi satu angka desimal.
top_pages[] array<object> Halaman teratas yang diurutkan berdasarkan pageviews.
top_pages[].rank integer Peringkat dalam snapshot lengkap saat menggunakan paginasi; peringkat berlanjut di seluruh halaman.
top_pages[].title string Judul halaman.
top_pages[].author string Penulis jika tersedia.
top_pages[].pubdate string Tanggal publikasi jika tersedia.
top_pages[].url string Path atau URL ringkas.
top_pages[].url_full string URL absolut jika tersedia.
top_pages[].url_id string Pengidentifikasi URL yang stabil.
top_pages[].thumbnail string URL thumbnail jika tersedia.
top_pages[].pageviews integer Pageviews untuk rentang hasil resolusi.
generated_at string Stempel waktu UTC saat payload dibuat.
pagination object Hanya ada dalam mode paginasi. Paling banyak 2000 artikel tersedia di seluruh halaman.
pagination.limit integer Ukuran halaman efektif, dari 1 hingga 100.
pagination.offset integer Posisi halaman yang diminta, dimulai dari nol.
pagination.total integer Jumlah artikel dalam snapshot ini, dibatasi hingga 2000. Nilai ini bukan jumlah URL yang cocok tanpa batas.
pagination.max_results integer Jumlah maksimum artikel per snapshot: 2000.
pagination.has_more boolean Menunjukkan apakah halaman lain tersedia dalam snapshot ini.
pagination.next_offset integer|null Kirim nilai ini sebagai offset untuk halaman berikutnya. Null berarti sudah mencapai akhir.
pagination.snapshot_id string ID opak untuk permintaan berikutnya yang menggunakan parameter snapshot. Terikat pada pengguna terautentikasi dan tracker.
pagination.expires_at string Waktu kedaluwarsa tetap dalam UTC, 10 menit setelah penyimpanan. Pembacaan halaman tidak memperpanjangnya.

Kebaruan dan caching

Permintaan tanpa paginasi menggunakan microcache 60 detik dan fallback historis yang sudah ada. Paginasi menyimpan snapshot yang tidak dapat diubah di Stats Redis lokal selama 600 detik, dengan kedaluwarsa otomatis dan tanpa perpanjangan bergulir. Permintaan awal yang identik dari pengguna yang sama dalam 60 detik dapat menggunakan kembali snapshot, jadi gunakan expires_at sebagai batas waktu. Permintaan lanjutan tidak pernah membuat ulang data atau menggunakan snapshot lain sebagai fallback.

Error

HTTP Kode Deskripsi
400 site_required Parameter site yang wajib tidak ada.
401 missing_token Header Authorization tidak ada.
401 invalid_token Token tidak valid atau telah dicabut.
403 site_not_authorized Kunci API tidak memiliki akses ke tracker ini.
429 rate_limit_exceeded Rate limit telah terlampaui.
503 redis_unavailable Backend realtime sedang tidak tersedia.
503 clickhouse_unavailable Data historis sedang tidak tersedia.
500 encoding_failed Respons Recap tidak dapat dikodekan.
400 invalid_pagination Parameter kueri paginasi harus berupa nilai skalar.
400 invalid_offset Offset harus berupa bilangan bulat dari 0 hingga 2000.
400 invalid_snapshot ID snapshot memiliki format yang tidak valid.
400 snapshot_required Offset yang lebih besar dari nol memerlukan ID snapshot. Mulai dengan offset=0.
400 snapshot_mismatch Preset, tanggal, atau pencarian berbeda dari permintaan awal.
410 snapshot_expired Snapshot telah kedaluwarsa atau tidak lagi tersedia dalam konteks pengguna/tracker ini. Mulai ulang dengan offset=0 tanpa snapshot.
503 snapshot_storage_unavailable Penyimpanan snapshot tidak dapat dibaca atau ditulisi. Coba lagi; ID snapshot yang ada harus tetap sama.
503 recap_unavailable Snapshot baru yang lengkap belum dapat dibuat. Coba lagi beberapa saat kemudian. 
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}