GET /v1/recap | Dokumentace NowMetrix REST API

Požadavek

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

Recap použijte, když vaše integrace potřebuje pracovat s historickými daty: pro historické přehledy, exporty nejčtenějších stránek, vlastní období nebo výsledky filtrované vyhledáváním.

Ověření

Vyžaduje klíč API v hlavičce Authorization: Authorization: Bearer nm_YOUR_KEY.

Parametry dotazu

Název	Typ	Povinný	Popis
`site`	`string`	povinné	ID trackeru. Klíč API musí mít k tomuto trackeru přístup.
`preset`	`string`	volitelné	Předvolba období. Jedna z hodnot `today`, `yesterday`, `last7`, `last14`, `last30`, `last90`, `this_month`, `last_month`, `all_time`, `custom`. Výchozí hodnota: `last30`.
`start`	`date`	volitelné	Počáteční datum pro `preset=custom`. Formát: `YYYY-MM-DD`.
`end`	`date`	volitelné	Koncové datum pro `preset=custom`. Formát: `YYYY-MM-DD`.
`limit`	`integer`	volitelné	Maximální počet nejčtenějších stránek v jedné odpovědi včetně stránkovaných odpovědí. Hodnoty se omezí na 1–100. Výchozí hodnota: 100.
`q`	`string`	volitelné	Hledaný výraz pro nejčtenější stránky. Vyhledává v URL, názvu nebo autorovi. Alias: `search`.
`search`	`string`	volitelné	Alias pro `q`.
`offset`	`integer`	volitelné	Stránkování zahájíte hodnotou `offset=0`. Celé číslo od 0 do 2000. Další stránky vyžadují `snapshot`. Bez parametru offset nebo snapshot zůstane stávající odpověď beze změny.
`snapshot`	`string`	volitelné	Použijte hodnotu `pagination.snapshot_id` z první odpovědi. Opakujte původní parametry site, preset, start, end a search. Velikost stránky se může změnit. Parametr snapshot vynechte, pokud chcete zahájit nové procházení.

Příklad cURL

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

Příklad odpovědi

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

Stránkování

Přidejte offset=0 a zapněte stránkování. Každá odpověď obsahuje nejvýše 100 článků; snapshot obsahuje nejvýše 2000 článků. Bez parametru offset nebo snapshot zůstane stávající formát odpovědi a limit beze změny.

Pro každou další stránku odešlete pagination.next_offset jako offset a pagination.snapshot_id jako snapshot. Opakujte původní parametry site, preset, start, end a search včetně vlastních dat. Jakmile je next_offset hodnotou null, skončete. Offset, který je roven dostupnému počtu nebo jej přesahuje, vrátí prázdné pole top_pages.

Pořadí článků, zobrazení stránek, denní hodnoty, souhrn a generated_at zůstávají na všech stránkách stejné, včetně období obsahujících dnešek. Souhrnné metriky pokrývají celé vybrané období; pagination.total zahrnuje pouze články v omezeném snapshotu. Každý požadavek stále vyžaduje platné ověření a započítává se do limitu požadavků trackeru.

Platnost snapshotu vyprší po 10 minutách a při čtení se neprodlužuje. Při HTTP 410 zahoďte neúplné procházení a začněte znovu s offset=0 bez parametru snapshot. Níže uvedené příklady ukazují první požadavek, pokračování a dodatečný objekt 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"
  }
}

Pole odpovědi

Pole	Typ	Popis
`site`	`string`	ID trackeru použité v požadavku.
`preset`	`string`	Vyhodnocená předvolba použitá pro odpověď.
`timezone`	`string`	Časové pásmo trackeru použité k určení místních dat.
`range`	`object`	Vyhodnocené období s údaji from, to, label a počtem dnů.
`limits`	`object`	Limity dostupné historie trackeru.
`search.query`	`string`	Normalizovaný hledaný výraz použitý k filtrování nejčtenějších stránek.
`daily[]`	`array<object>`	Počet zobrazení stránek a návštěv pro vyhodnocené období po jednotlivých dnech.
`summary.total_pageviews`	`integer`	Celkový počet zobrazení stránek za vyhodnocené období.
`summary.total_visits`	`integer`	Celkový počet návštěv za vyhodnocené období.
`summary.pages_per_visitor`	`number`	Počet zobrazení stránek dělený počtem návštěv, zaokrouhlený na jedno desetinné místo.
`top_pages[]`	`array<object>`	Nejčtenější stránky seřazené podle počtu zobrazení stránek.
`top_pages[].rank`	`integer`	Pořadí v celém snapshotu při stránkování; pořadí pokračuje napříč stránkami.
`top_pages[].title`	`string`	Název stránky.
`top_pages[].author`	`string`	Autor, pokud je k dispozici.
`top_pages[].pubdate`	`string`	Datum publikace, pokud je k dispozici.
`top_pages[].url`	`string`	Cesta nebo zkrácená URL.
`top_pages[].url_full`	`string`	Absolutní URL, pokud je k dispozici.
`top_pages[].url_id`	`string`	Stabilní identifikátor URL.
`top_pages[].thumbnail`	`string`	URL náhledu, pokud je k dispozici.
`top_pages[].pageviews`	`integer`	Počet zobrazení stránek za vyhodnocené období.
`generated_at`	`string`	Časové razítko UTC označující, kdy byla data vygenerována.
`pagination`	`object`	Zobrazuje se pouze v režimu stránkování. Napříč všemi stránkami je dostupných nejvýše 2000 článků.
`pagination.limit`	`integer`	Efektivní velikost stránky od 1 do 100.
`pagination.offset`	`integer`	Počáteční pozice požadované stránky, počítaná od nuly.
`pagination.total`	`integer`	Počet článků v tomto snapshotu, nejvýše 2000. Nejde o neomezený počet odpovídajících URL.
`pagination.max_results`	`integer`	Maximální počet článků v snapshotu: 2000.
`pagination.has_more`	`boolean`	Určuje, zda je v tomto snapshotu dostupná další stránka.
`pagination.next_offset`	`integer\|null`	Tuto hodnotu předejte jako offset pro další stránku. Hodnota null znamená, že bylo dosaženo konce.
`pagination.snapshot_id`	`string`	Neprůhledné ID pro další požadavky s parametrem snapshot. Je vázané na ověřeného uživatele a tracker.
`pagination.expires_at`	`string`	Pevný čas vypršení platnosti v UTC, 10 minut po uložení. Čtení stránek platnost neprodlužuje.

Aktuálnost a cachování

Požadavky bez stránkování používají stávající 60sekundovou mikrocache a historická záložní data. Stránkování ukládá neměnný snapshot do místního Stats Redis na 600 sekund s automatickým vypršením platnosti bez jejího průběžného prodlužování. Totožné počáteční požadavky od stejného uživatele během 60 sekund mohou znovu použít snapshot, proto jako čas vypršení použijte expires_at. Pokračování nikdy data znovu nevytváří ani nepoužívá jiný snapshot jako záložní.

Chyby

HTTP	Kód	Popis
400	`site_required`	Chybí povinný parametr site.
401	`missing_token`	Chybí hlavička Authorization.
401	`invalid_token`	Token je neplatný nebo odvolaný.
403	`site_not_authorized`	Klíč API nemá k tomuto trackeru přístup.
429	`rate_limit_exceeded`	Limit požadavků byl překročen.
503	`redis_unavailable`	Backend Realtime je dočasně nedostupný.
503	`clickhouse_unavailable`	Historická data jsou dočasně nedostupná.
500	`encoding_failed`	Odpověď Recap se nepodařilo zakódovat.
400	`invalid_pagination`	Parametry dotazu pro stránkování musí být skalární hodnoty.
400	`invalid_offset`	Offset musí být celé číslo od 0 do 2000.
400	`invalid_snapshot`	ID snapshotu má neplatný formát.
400	`snapshot_required`	Offsety větší než nula vyžadují ID snapshotu. Začněte s offset=0.
400	`snapshot_mismatch`	Předvolba, data nebo vyhledávání se liší od původního požadavku.
410	`snapshot_expired`	Platnost snapshotu vypršela nebo už není v kontextu tohoto uživatele či trackeru dostupný. Začněte znovu s offset=0 bez parametru snapshot.
503	`snapshot_storage_unavailable`	Úložiště snapshotů nelze číst ani do něj zapisovat. Zkuste to znovu; stávající ID snapshotu musí zůstat beze změny.
503	`recap_unavailable`	Kompletní nový snapshot momentálně nelze vytvořit. Zkuste to za chvíli znovu.

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