REST-API-Endpunkt

GET /v1/recap

Recap-Daten, zusammenfassende Kennzahlen und Top Pages für Zeitraumvorgaben oder einen benutzerdefinierten Zeitraum.

Anfrage

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

Verwenden Sie Recap, wenn Ihre Integration auf vergangene Daten zugreifen muss: für historische Auswertungen, Exporte von Top Pages, benutzerdefinierte Zeiträume oder durch Suchbegriffe gefilterte Ergebnisse.

Authentifizierung

Erfordert einen API-Schlüssel im Authorization-Header: Authorization: Bearer nm_YOUR_KEY.

Abfrageparameter

Name Typ Erforderlich Beschreibung
site string erforderlich Tracker-ID. Der API-Schlüssel muss Zugriff auf diesen Tracker haben.
preset string optional Zeitraumvorgabe. Eine der folgenden Optionen: today, yesterday, last7, last14, last30, last90, this_month, last_month, all_time, custom. Standard: last30.
start date optional Startdatum für preset=custom. Format: YYYY-MM-DD.
end date optional Enddatum für preset=custom. Format: YYYY-MM-DD.
limit integer optional Maximale Anzahl Top Pages pro Antwort, auch bei Pagination. Werte werden auf 1–100 begrenzt. Standard: 100.
q string optional Suchbegriff für Top Pages. Durchsucht URL, Titel oder Autor. Alias: search.
search string optional Alias für q.
offset integer optional Starten Sie die Pagination mit offset=0. Ganzzahl von 0 bis 2000. Folgeseiten benötigen snapshot. Ohne offset oder snapshot bleibt die bisherige Antwort unverändert.
snapshot string optional Verwenden Sie pagination.snapshot_id aus der ersten Antwort. Wiederholen Sie die ursprünglichen Parameter site, preset, start, end und den Suchfilter. Die Seitengrösse darf wechseln. Für einen neuen Durchlauf lassen Sie snapshot weg.

cURL-Beispiel

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

Beispielantwort

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

Pagination

Ergänzen Sie offset=0, um die Pagination zu aktivieren. Jede Antwort enthält höchstens 100 Artikel, der Snapshot insgesamt höchstens 2000. Ohne offset oder snapshot bleiben das bisherige Antwortformat und Limit unverändert.

Senden Sie für jede Folgeseite pagination.next_offset als offset und pagination.snapshot_id als snapshot. Wiederholen Sie die ursprünglichen Parameter site, preset, start, end und den Suchfilter, auch eigene Datumsgrenzen. Beenden Sie den Abruf, sobald next_offset null ist. Ab der verfügbaren Artikelanzahl liefert offset ein leeres top_pages-Array.

Artikelreihenfolge, Pageviews, Tageswerte, Gesamtkennzahlen und generated_at bleiben über alle Seiten stabil, auch bei Zeiträumen mit dem heutigen Tag. Die Gesamtkennzahlen umfassen den gesamten gewählten Zeitraum; pagination.total zählt nur die Artikel im begrenzten Snapshot. Jeder Request benötigt weiterhin eine gültige Berechtigung und zählt zum Rate-Limit des Trackers.

Snapshots laufen nach 10 Minuten ab; Lesezugriffe verlängern sie nicht. Verwerfen Sie bei HTTP 410 den unvollständigen Durchlauf und beginnen Sie mit offset=0 ohne snapshot neu. Die Beispiele zeigen den ersten Request, einen Folgeaufruf und das zusätzliche pagination-Objekt.

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

Antwortfelder

Feld Typ Beschreibung
site string Tracker-ID, die für die Anfrage verwendet wurde.
preset string Für die Antwort ermittelte Zeitraumvorgabe.
timezone string Zeitzone des Trackers, anhand derer die lokalen Daten ermittelt werden.
range object Ermittelter Zeitraum mit Start, Ende, Bezeichnung und Anzahl der Tage.
limits object Für den Tracker verfügbare Grenzen des Datenbestands.
search.query string Normalisierte Suchanfrage, die zur Filterung der Top Pages verwendet wird.
daily[] array<object> Tägliche Pageviews und Besuche für den ermittelten Zeitraum.
summary.total_pageviews integer Pageviews insgesamt über den ermittelten Zeitraum.
summary.total_visits integer Besuche insgesamt über den ermittelten Zeitraum.
summary.pages_per_visitor number Pageviews geteilt durch Besuche, auf eine Dezimalstelle gerundet.
top_pages[] array<object> Nach Pageviews sortierte Top Pages.
top_pages[].rank integer Bei Pagination der Rang im vollständigen Snapshot; die Rangfolge läuft über die Seiten hinweg weiter.
top_pages[].title string Titel der Seite.
top_pages[].author string Autor, sofern verfügbar.
top_pages[].pubdate string Veröffentlichungsdatum, sofern verfügbar.
top_pages[].url string Pfad oder verkürzte URL.
top_pages[].url_full string Absolute URL, sofern verfügbar.
top_pages[].url_id string Stabile URL-Kennung.
top_pages[].thumbnail string Thumbnail-URL, sofern verfügbar.
top_pages[].pageviews integer Pageviews für den ermittelten Zeitraum.
generated_at string UTC-Zeitstempel der Payload-Erstellung.
pagination object Nur im Pagination-Modus vorhanden. Über alle Seiten sind höchstens 2000 Artikel verfügbar.
pagination.limit integer Tatsächliche Seitengrösse von 1 bis 100.
pagination.offset integer Position der angefragten Seite, beginnend bei 0.
pagination.total integer Artikelanzahl in diesem Snapshot, auf 2000 begrenzt. Dies ist nicht die unbeschränkte Anzahl passender URLs.
pagination.max_results integer Maximale Artikelanzahl pro Snapshot: 2000.
pagination.has_more boolean Gibt an, ob im Snapshot eine weitere Seite verfügbar ist.
pagination.next_offset integer|null Übergeben Sie diesen Wert als offset für die nächste Seite. Null bedeutet, dass das Ende erreicht ist.
pagination.snapshot_id string Nicht interpretierbare ID für Folgeaufrufe mit dem Parameter snapshot. An den authentifizierten Benutzer und Tracker gebunden.
pagination.expires_at string Fester Ablaufzeitpunkt in UTC, 10 Minuten nach Speicherung. Seitenabrufe verlängern die Gültigkeit nicht.

Aktualität und Zwischenspeicherung

Requests ohne Pagination verwenden den bisherigen 60-Sekunden-Microcache und historischen Fallback. Pagination speichert einen unveränderlichen Snapshot für 600 Sekunden im lokalen Stats-Redis; er läuft automatisch ab und wird beim Lesen nicht verlängert. Gleiche Starts desselben Benutzers innerhalb von 60 Sekunden können einen Snapshot wiederverwenden; massgeblich ist deshalb expires_at. Folgeseiten bauen die Daten nie neu auf und verwenden keinen anderen Snapshot als Fallback.

Fehler

HTTP Code Beschreibung
400 site_required Der erforderliche site-Parameter fehlt.
401 missing_token Der Authorization-Header fehlt.
401 invalid_token Das Token ist ungültig oder wurde widerrufen.
403 site_not_authorized Der API-Schlüssel hat keinen Zugriff auf diesen Tracker.
429 rate_limit_exceeded Das Rate-Limit wurde überschritten.
503 redis_unavailable Das Echtzeit-Backend ist vorübergehend nicht verfügbar.
503 clickhouse_unavailable Historische Daten sind vorübergehend nicht verfügbar.
500 encoding_failed Die Recap-Antwort konnte nicht kodiert werden.
400 invalid_pagination Pagination-Parameter müssen skalare Werte sein.
400 invalid_offset Offset muss eine Ganzzahl von 0 bis 2000 sein.
400 invalid_snapshot Das Format der Snapshot-ID ist ungültig.
400 snapshot_required Für offset grösser als null ist eine Snapshot-ID erforderlich. Beginnen Sie mit offset=0.
400 snapshot_mismatch Vorgabe, Datumswerte oder Suchfilter weichen vom ursprünglichen Request ab.
410 snapshot_expired Der Snapshot ist abgelaufen oder für diesen Benutzer/Tracker nicht mehr verfügbar. Beginnen Sie erneut mit offset=0 und ohne snapshot.
503 snapshot_storage_unavailable Der Snapshot-Speicher kann nicht gelesen oder beschrieben werden. Wiederholen Sie den Request; behalten Sie eine bereits erhaltene Snapshot-ID bei.
503 recap_unavailable Ein vollständiger neuer Snapshot kann derzeit nicht erstellt werden. Versuchen Sie es in Kürze erneut. 
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}