GET /v1/recap | Dokumentacja REST API NowMetrix

Żądanie

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

Recap służy do analizy danych historycznych, w tym do raportowania, eksportu najpopularniejszych stron, obsługi niestandardowych zakresów dat oraz filtrowania wyników za pomocą wyszukiwania.

Uwierzytelnianie

Wymagany jest klucz API w nagłówku Authorization: Bearer nm_YOUR_KEY.

Parametry zapytania

Nazwa	Typ	Wymagany	Opis
`site`	`string`	wymagany	Identyfikator trackera. Klucz API musi zapewniać dostęp do tego trackera.
`preset`	`string`	opcjonalny	Preset zakresu dat. Jedna z wartości: `today`, `yesterday`, `last7`, `last14`, `last30`, `last90`, `this_month`, `last_month`, `all_time`, `custom`. Wartość domyślna: `last30`.
`start`	`date`	opcjonalny	Data początkowa dla `preset=custom`. Format: `YYYY-MM-DD`.
`end`	`date`	opcjonalny	Data końcowa dla `preset=custom`. Format: `YYYY-MM-DD`.
`limit`	`integer`	opcjonalny	Maksymalna liczba najpopularniejszych stron w odpowiedzi, także w odpowiedziach stronicowanych. Wartość jest ograniczana do zakresu 1–100. Wartość domyślna: 100.
`q`	`string`	opcjonalny	Wyszukiwana fraza dotycząca najpopularniejszych stron. Dopasowanie obejmuje URL, tytuł lub autora. Alias: `search`.
`search`	`string`	opcjonalny	Alias parametru `q`.
`offset`	`integer`	opcjonalny	Rozpoczęcie stronicowania za pomocą `offset=0`. Liczba całkowita od 0 do 2000. Kolejne strony wymagają parametru `snapshot`. Bez parametru offset lub snapshot dotychczasowa odpowiedź pozostaje bez zmian.
`snapshot`	`string`	opcjonalny	Należy użyć wartości `pagination.snapshot_id` z pierwszej odpowiedzi. Należy powtórzyć pierwotne parametry site, preset, start, end i search. Rozmiar strony może się zmienić. Pominięcie snapshot rozpoczyna nowe przejście przez wyniki.

Przykład cURL

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

Przykład odpowiedzi

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

Stronicowanie

Dodanie offset=0 włącza stronicowanie. Każda odpowiedź zawiera maksymalnie 100 artykułów, a migawka — maksymalnie 2000. Bez parametru offset lub snapshot dotychczasowy format odpowiedzi i limit pozostają bez zmian.

Aby pobrać kolejną stronę, należy przesłać pagination.next_offset jako offset oraz pagination.snapshot_id jako snapshot. Należy powtórzyć pierwotne parametry site, preset, start, end i search, w tym niestandardowe daty. Należy zakończyć pobieranie, gdy next_offset ma wartość null. Offset równy liczbie dostępnych elementów lub od niej większy zwraca pustą tablicę top_pages.

Kolejność artykułów, wartości pageviews i daily, podsumowanie oraz generated_at pozostają stałe na wszystkich stronach, także w zakresach obejmujących bieżący dzień. Statystyki podsumowania dotyczą całego wybranego zakresu, natomiast pagination.total obejmuje tylko artykuły znajdujące się w ograniczonej migawce. Każde żądanie nadal wymaga prawidłowego uwierzytelnienia i jest uwzględniane w limicie zapytań trackera.

Migawki wygasają po 10 minutach i nie są odnawiane podczas odczytu. Po otrzymaniu HTTP 410 należy odrzucić częściowo pobrane dane i rozpocząć ponownie od offset=0 bez parametru snapshot. Poniższe przykłady przedstawiają pierwsze żądanie, kontynuację oraz dodatkowy obiekt paginacji.

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

Pola odpowiedzi

Pole	Typ	Opis
`site`	`string`	Identyfikator trackera użyty w żądaniu.
`preset`	`string`	Rozpoznany preset użyty w odpowiedzi.
`timezone`	`string`	Strefa czasowa trackera użyta do określenia dat lokalnych.
`range`	`object`	Rozpoznany zakres dat zawierający wartości from, to, label oraz liczbę dni.
`limits`	`object`	Limity dostępnej historii dla trackera.
`search.query`	`string`	Znormalizowane zapytanie użyte do filtrowania najpopularniejszych stron.
`daily[]`	`array<object>`	Dzienna liczba odsłon i wizyt dla rozpoznanego zakresu.
`summary.total_pageviews`	`integer`	Łączna liczba odsłon w rozpoznanym zakresie.
`summary.total_visits`	`integer`	Łączna liczba wizyt w rozpoznanym zakresie.
`summary.pages_per_visitor`	`number`	Liczba odsłon podzielona przez liczbę wizyt, zaokrąglona do jednego miejsca po przecinku.
`top_pages[]`	`array<object>`	Najpopularniejsze strony posortowane według liczby odsłon.
`top_pages[].rank`	`integer`	Pozycja w pełnej migawce podczas stronicowania; numeracja jest kontynuowana na kolejnych stronach.
`top_pages[].title`	`string`	Tytuł strony.
`top_pages[].author`	`string`	Autor, jeśli jest dostępny.
`top_pages[].pubdate`	`string`	Data publikacji, jeśli jest dostępna.
`top_pages[].url`	`string`	Ścieżka lub skrócony URL.
`top_pages[].url_full`	`string`	Pełny URL, jeśli jest dostępny.
`top_pages[].url_id`	`string`	Stały identyfikator URL.
`top_pages[].thumbnail`	`string`	URL miniatury, jeśli jest dostępny.
`top_pages[].pageviews`	`integer`	Liczba odsłon w rozpoznanym zakresie.
`generated_at`	`string`	Znacznik czasu UTC wskazujący moment wygenerowania danych.
`pagination`	`object`	Obecny tylko w trybie stronicowania. Łącznie na wszystkich stronach dostępnych jest maksymalnie 2000 artykułów.
`pagination.limit`	`integer`	Efektywny rozmiar strony od 1 do 100.
`pagination.offset`	`integer`	Pozycja żądanej strony liczona od zera.
`pagination.total`	`integer`	Liczba artykułów w tej migawce, ograniczona do 2000. Nie jest to pełna liczba pasujących URL-i bez ograniczenia.
`pagination.max_results`	`integer`	Maksymalna liczba artykułów w migawce: 2000.
`pagination.has_more`	`boolean`	Informacja, czy w tej migawce dostępna jest kolejna strona.
`pagination.next_offset`	`integer\|null`	Wartość, którą należy przekazać jako offset dla kolejnej strony. Wartość null oznacza osiągnięcie końca.
`pagination.snapshot_id`	`string`	Nieprzejrzysty identyfikator do kolejnych żądań z parametrem snapshot. Jest powiązany z uwierzytelnionym użytkownikiem i trackerem.
`pagination.expires_at`	`string`	Stały termin wygaśnięcia w UTC, przypadający 10 minut po zapisaniu. Odczyt stron nie przedłuża tego terminu.

Aktualność danych i buforowanie

Żądania bez stronicowania korzystają z istniejącej 60-sekundowej mikropamięci podręcznej oraz awaryjnego mechanizmu danych historycznych. W trybie stronicowania niezmienna migawka jest zapisywana w lokalnym Stats Redis na 600 sekund i automatycznie wygasa; jej ważność nie jest odnawiana przy odczycie. Identyczne żądania początkowe tego samego użytkownika w ciągu 60 sekund mogą ponownie wykorzystać migawkę, dlatego jako termin graniczny należy traktować expires_at. Żądania kontynuacji nigdy nie przebudowują danych ani nie korzystają awaryjnie z innej migawki.

Błędy

HTTP	Kod	Opis
400	`site_required`	Brakuje wymaganego parametru site.
401	`missing_token`	Brakuje nagłówka Authorization.
401	`invalid_token`	Token jest nieprawidłowy lub został unieważniony.
403	`site_not_authorized`	Klucz API nie zapewnia dostępu do tego trackera.
429	`rate_limit_exceeded`	Przekroczono limit zapytań.
503	`redis_unavailable`	Backend danych bieżących jest tymczasowo niedostępny.
503	`clickhouse_unavailable`	Dane historyczne są tymczasowo niedostępne.
500	`encoding_failed`	Nie udało się zakodować odpowiedzi Recap.
400	`invalid_pagination`	Parametry zapytania dotyczące stronicowania muszą być wartościami skalarnymi.
400	`invalid_offset`	Offset musi być liczbą całkowitą od 0 do 2000.
400	`invalid_snapshot`	Identyfikator migawki ma nieprawidłowy format.
400	`snapshot_required`	Offset większy od zera wymaga identyfikatora migawki. Należy rozpocząć od offset=0.
400	`snapshot_mismatch`	Preset, daty lub wyszukiwanie różnią się od wartości z pierwotnego żądania.
410	`snapshot_expired`	Migawka wygasła lub nie jest już dostępna w kontekście tego użytkownika i trackera. Należy rozpocząć ponownie od offset=0 bez parametru snapshot.
503	`snapshot_storage_unavailable`	Nie można odczytać ani zapisać migawki. Należy ponowić próbę; istniejący identyfikator migawki musi pozostać bez zmian.
503	`recap_unavailable`	Nie można obecnie utworzyć kompletnej nowej migawki. Należy spróbować ponownie za chwilę.

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