krajnja točka REST API-ja

GET /v1/recap

Podaci za Recap, sažete metrike i najpopularnije stranice za unaprijed definirana razdoblja ili prilagođeni raspon datuma.

Zahtjev

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

Upotrijebite Recap kada Vaša integracija treba dohvatiti povijesne podatke: povijesna izvješća, izvoz najpopularnijih stranica, prilagođene raspone datuma ili rezultate filtrirane pretraživanjem.

Autentikacija

Potreban je API ključ u zaglavlju Authorization, u obliku Authorization: Bearer nm_YOUR_KEY.

Parametri upita

Naziv Vrsta Obavezno Opis
site string obavezno Tracker ID. API ključ mora imati pristup tom trackeru.
preset string neobavezno Unaprijed definirano razdoblje. Jedna od vrijednosti today, yesterday, last7, last14, last30, last90, this_month, last_month, all_time, custom. Zadano: last30.
start date neobavezno Početni datum za preset=custom. Format: YYYY-MM-DD.
end date neobavezno Završni datum za preset=custom. Format: YYYY-MM-DD.
limit integer neobavezno Maksimalan broj najpopularnijih stranica po odgovoru, uključujući odgovore s paginacijom. Vrijednosti se ograničavaju na raspon 1–100. Zadano: 100.
q string neobavezno Pojam za pretraživanje najpopularnijih stranica. Podudaranje se traži u URL-u, naslovu ili autoru. Alias: search.
search string neobavezno Alias za q.
offset integer neobavezno Paginaciju započnite s offset=0. Cijeli broj od 0 do 2000. Za sljedeće stranice potreban je snapshot. Bez parametra offset ili snapshot postojeći odgovor ostaje nepromijenjen.
snapshot string neobavezno Upotrijebite pagination.snapshot_id iz prvog odgovora. Ponovite izvorne parametre site, preset, start, end i search. Veličina stranice može se promijeniti. Izostavite snapshot da biste započeli novo dohvaćanje.

Primjer cURL-a

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

Primjer odgovora

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

Paginacija

Dodajte offset=0 da biste uključili paginaciju. Svaki odgovor sadržava najviše 100 članaka, a snimka najviše 2000 članaka. Bez parametra offset ili snapshot format postojećeg odgovora i ograničenje ostaju nepromijenjeni.

Za svaku sljedeću stranicu pošaljite pagination.next_offset kao offset i pagination.snapshot_id kao snapshot. Ponovite izvorne parametre site, preset, start, end i search, uključujući prilagođene datume. Zaustavite se kada je next_offset null. Offset jednak ili veći od dostupnog broja vraća prazan niz top_pages.

Redoslijed članaka, broj pregleda stranica, dnevne vrijednosti, sažetak i generated_at ostaju nepromijenjeni na svim stranicama, uključujući raspone koji sadržavaju današnji dan. Sažete metrike obuhvaćaju cijeli odabrani raspon, a pagination.total obuhvaća samo članke u ograničenoj snimci. Svaki zahtjev i dalje zahtijeva valjanu autorizaciju i ubraja se u ograničenje broja zahtjeva za tracker.

Snimke istječu nakon 10 minuta; čitanje ne produljuje njihov rok valjanosti. U slučaju HTTP 410 odbacite djelomično dohvaćanje i ponovno ga pokrenite s offset=0, bez parametra snapshot. Primjeri u nastavku prikazuju prvi zahtjev, nastavak i dodatni objekt paginacije.

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

Polja odgovora

Polje Vrsta Opis
site string Tracker ID upotrijebljen za zahtjev.
preset string Razriješeno unaprijed definirano razdoblje upotrijebljeno za odgovor.
timezone string Vremenska zona trackera upotrijebljena za određivanje lokalnih datuma.
range object Razriješeni raspon datuma s poljima from, to, label i brojem dana.
limits object Ograničenja dostupne povijesti za tracker.
search.query string Normalizirani upit za pretraživanje upotrijebljen za filtriranje najpopularnijih stranica.
daily[] array<object> Dnevni broj pregleda stranica i posjeta za razriješeni raspon.
summary.total_pageviews integer Ukupan broj pregleda stranica u razriješenom rasponu.
summary.total_visits integer Ukupan broj posjeta u razriješenom rasponu.
summary.pages_per_visitor number Broj pregleda stranica podijeljen brojem posjeta, zaokružen na jednu decimalu.
top_pages[] array<object> Najpopularnije stranice poredane prema broju pregleda stranica.
top_pages[].rank integer Poredak u potpunoj snimci pri upotrebi paginacije; poredak se nastavlja na sljedećim stranicama.
top_pages[].title string Naslov stranice.
top_pages[].author string Autor, ako je dostupan.
top_pages[].pubdate string Datum objave, ako je dostupan.
top_pages[].url string Putanja ili skraćeni URL.
top_pages[].url_full string Apsolutni URL, ako je dostupan.
top_pages[].url_id string Stabilni identifikator URL-a.
top_pages[].thumbnail string URL minijature, ako je dostupan.
top_pages[].pageviews integer Broj pregleda stranice za razriješeni raspon.
generated_at string Vremenska oznaka u UTC-u koja označava kada je sadržaj generiran.
pagination object Prisutan samo u načinu rada s paginacijom. Na svim je stranicama dostupno najviše 2000 članaka.
pagination.limit integer Učinkovita veličina stranice, od 1 do 100.
pagination.offset integer Pozicija tražene stranice koja počinje od nule.
pagination.total integer Broj članaka u ovoj snimci, ograničen na 2000. To nije neograničeni broj URL-ova koji odgovaraju kriterijima.
pagination.max_results integer Maksimalan broj članaka po snimci: 2000.
pagination.has_more boolean Označava postoji li u ovoj snimci još jedna stranica.
pagination.next_offset integer|null Proslijedite ovu vrijednost kao offset za sljedeću stranicu. Null označava da je dosegnut kraj.
pagination.snapshot_id string Neprozirni ID za sljedeće zahtjeve koji upotrebljavaju parametar snapshot. Povezan je s autentificiranim korisnikom i trackerom.
pagination.expires_at string Fiksno vrijeme isteka u UTC-u, 10 minuta nakon pohrane. Čitanje stranica ne produljuje rok.

Aktualnost i predmemoriranje

Zahtjevi bez paginacije upotrebljavaju postojeću mikro-predmemoriju od 60 sekundi i povijesni pričuvni mehanizam. Paginacija pohranjuje nepromjenjivu snimku u lokalni Stats Redis na 600 sekundi, uz automatski istek i bez kliznog produljenja. Istovjetni početni zahtjevi koje isti korisnik pošalje unutar 60 sekundi mogu ponovno upotrijebiti snimku, stoga kao rok upotrebljavajte expires_at. Nastavci nikada ponovno ne izrađuju podatke niti kao pričuvnu opciju upotrebljavaju drugu snimku.

Pogreške

HTTP Kôd Opis
400 site_required Nedostaje obavezni parametar site.
401 missing_token Nedostaje zaglavlje Authorization.
401 invalid_token Token nije valjan ili je opozvan.
403 site_not_authorized API ključ nema pristup tom trackeru.
429 rate_limit_exceeded Prekoračeno je ograničenje broja zahtjeva.
503 redis_unavailable Sustav u pozadini za podatke u stvarnom vremenu privremeno nije dostupan.
503 clickhouse_unavailable Povijesni podaci privremeno nisu dostupni.
500 encoding_failed Odgovor Recap nije moguće kodirati.
400 invalid_pagination Parametri upita za paginaciju moraju biti skalarne vrijednosti.
400 invalid_offset Offset mora biti cijeli broj od 0 do 2000.
400 invalid_snapshot ID snimke ima nevaljan format.
400 snapshot_required Za offsete veće od nule potreban je ID snimke. Započnite s offset=0.
400 snapshot_mismatch Unaprijed definirano razdoblje, datumi ili pretraživanje razlikuju se od izvornog zahtjeva.
410 snapshot_expired Snimka je istekla ili više nije dostupna u kontekstu ovog korisnika i trackera. Ponovno pokrenite postupak s offset=0 i bez parametra snapshot.
503 snapshot_storage_unavailable Nije moguće čitati ni zapisati pohranu snimke. Pokušajte ponovno; postojeći ID snimke mora ostati nepromijenjen.
503 recap_unavailable Trenutačno nije moguće izraditi potpunu novu snimku. Pokušajte ponovno uskoro. 
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}