GET /v1/recap | NowMetrix REST API-documentatie

Aanvraag

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

Gebruik Recap wanneer uw integratie historische gegevens, exports van Toppagina’s, aangepaste datumbereiken of met een zoekterm gefilterde resultaten nodig heeft.

Authenticatie

Vereist een API-sleutel in de Authorization-header: Authorization: Bearer nm_YOUR_KEY.

Queryparameters

Naam	Type	Verplicht	Beschrijving
`site`	`string`	verplicht	Tracker-ID. De API-sleutel moet toegang hebben tot deze tracker.
`preset`	`string`	optioneel	Vooraf ingestelde periode. Een van `today`, `yesterday`, `last7`, `last14`, `last30`, `last90`, `this_month`, `last_month`, `all_time`, `custom`. Standaard: `last30`.
`start`	`date`	optioneel	Begindatum voor `preset=custom`. Indeling: `YYYY-MM-DD`.
`end`	`date`	optioneel	Einddatum voor `preset=custom`. Indeling: `YYYY-MM-DD`.
`limit`	`integer`	optioneel	Maximumaantal toppagina’s per respons, ook bij paginering. Waarden worden begrensd tot 1–100. Standaard: 100.
`q`	`string`	optioneel	Zoekterm voor Toppagina’s. Doorzoekt de URL, titel en auteur. Alias: `search`.
`search`	`string`	optioneel	Alias voor `q`.
`offset`	`integer`	optioneel	Start de paginering met `offset=0`. Geheel getal van 0 tot 2000. Vervolgpagina’s vereisen `snapshot`. Zonder offset of snapshot blijft de bestaande respons ongewijzigd.
`snapshot`	`string`	optioneel	Gebruik `pagination.snapshot_id` uit de eerste respons. Herhaal de oorspronkelijke site, preset, start, end en zoekparameters. De paginagrootte mag wijzigen. Laat snapshot weg om een nieuwe reeks te starten.

cURL-voorbeeld

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

Voorbeeldresponse

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

Voeg offset=0 toe om paginering te activeren. Elke respons bevat maximaal 100 artikelen; de momentopname bevat maximaal 2000. Zonder offset of snapshot blijven het bestaande responsformaat en de limiet ongewijzigd.

Stuur voor elke volgende pagina pagination.next_offset als offset en pagination.snapshot_id als snapshot. Herhaal de oorspronkelijke site, preset, start, end en zoekparameters, inclusief aangepaste datums. Stop zodra next_offset null is. Een offset op of voorbij het beschikbare aantal geeft een lege top_pages-array.

De artikelvolgorde, Pageviews, dagwaarden, samenvatting en generated_at blijven gelijk op alle pagina’s, ook voor perioden met vandaag. De samenvattingswaarden omvatten de hele gekozen periode; pagination.total telt alleen artikelen in de begrensde momentopname. Elk verzoek vereist nog steeds geldige autorisatie en telt mee voor de trackerlimiet.

Momentopnamen verlopen na 10 minuten; lezen verlengt de geldigheid niet. Verwerp bij HTTP 410 de onvolledige reeks en begin opnieuw met offset=0 zonder snapshot. De voorbeelden tonen het eerste verzoek, een vervolgverzoek en het extra pagination-object.

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

Responsevelden

Veld	Type	Beschrijving
`site`	`string`	Tracker-ID die voor de aanvraag is gebruikt.
`preset`	`string`	De toegepaste preset voor deze response.
`timezone`	`string`	Tijdzone van de tracker die is gebruikt om lokale datums te bepalen.
`range`	`object`	Het vastgestelde datumbereik met from, to, label en het aantal dagen.
`limits`	`object`	Beschikbare limieten voor historische gegevens van de tracker.
`search.query`	`string`	Genormaliseerde zoekopdracht die voor het filteren van Toppagina’s is gebruikt.
`daily[]`	`array<object>`	Dagelijkse Pageviews en bezoeken voor het vastgestelde datumbereik.
`summary.total_pageviews`	`integer`	Totaal aantal Pageviews binnen het vastgestelde datumbereik.
`summary.total_visits`	`integer`	Totaal aantal bezoeken binnen het vastgestelde datumbereik.
`summary.pages_per_visitor`	`number`	Pageviews gedeeld door bezoeken, afgerond op één decimaal.
`top_pages[]`	`array<object>`	Toppagina’s, gesorteerd op Pageviews.
`top_pages[].rank`	`integer`	Bij paginering de rang in de volledige momentopname; de rangnummering loopt door over de pagina’s.
`top_pages[].title`	`string`	Paginatitel.
`top_pages[].author`	`string`	Auteur, indien beschikbaar.
`top_pages[].pubdate`	`string`	Publicatiedatum, indien beschikbaar.
`top_pages[].url`	`string`	Pad of verkorte URL.
`top_pages[].url_full`	`string`	Absolute URL, indien beschikbaar.
`top_pages[].url_id`	`string`	Stabiele URL-identificatie.
`top_pages[].thumbnail`	`string`	Thumbnail-URL, indien beschikbaar.
`top_pages[].pageviews`	`integer`	Aantal Pageviews binnen het vastgestelde datumbereik.
`generated_at`	`string`	UTC-tijdstip waarop de payload is gegenereerd.
`pagination`	`object`	Alleen aanwezig bij paginering. Over alle pagina’s zijn maximaal 2000 artikelen beschikbaar.
`pagination.limit`	`integer`	Effectieve paginagrootte, van 1 tot 100.
`pagination.offset`	`integer`	Positie van de aangevraagde pagina, beginnend bij 0.
`pagination.total`	`integer`	Aantal artikelen in deze momentopname, begrensd tot 2000. Dit is niet het onbeperkte aantal overeenkomende URL’s.
`pagination.max_results`	`integer`	Maximumaantal artikelen per momentopname: 2000.
`pagination.has_more`	`boolean`	Geeft aan of deze momentopname nog een pagina bevat.
`pagination.next_offset`	`integer\|null`	Gebruik deze waarde als offset voor de volgende pagina. Null betekent dat het einde is bereikt.
`pagination.snapshot_id`	`string`	Ondoorzichtige ID voor vervolgverzoeken via de parameter snapshot. Gekoppeld aan de geauthenticeerde gebruiker en tracker.
`pagination.expires_at`	`string`	Vast vervaltijdstip in UTC, 10 minuten na opslag. Het ophalen van pagina’s verlengt dit niet.

Actualiteit en caching

Verzoeken zonder paginering gebruiken de bestaande microcache van 60 seconden en de historische terugval. Paginering bewaart een onveranderlijke momentopname gedurende 600 seconden in de lokale Stats Redis, met automatische vervaldatum zonder verlenging bij lezen. Identieke starts van dezelfde gebruiker binnen 60 seconden kunnen een momentopname hergebruiken; houd daarom expires_at aan. Vervolgpagina’s bouwen de gegevens nooit opnieuw op en gebruiken geen andere momentopname als terugval.

Foutmeldingen

HTTP	Code	Beschrijving
400	`site_required`	De verplichte parameter site ontbreekt.
401	`missing_token`	De Authorization-header ontbreekt.
401	`invalid_token`	Het token is ongeldig of ingetrokken.
403	`site_not_authorized`	De API-sleutel heeft geen toegang tot deze tracker.
429	`rate_limit_exceeded`	De limiet voor aanvragen is overschreden.
503	`redis_unavailable`	De realtimebackend is tijdelijk niet beschikbaar.
503	`clickhouse_unavailable`	Historische gegevens zijn tijdelijk niet beschikbaar.
500	`encoding_failed`	De Recap-response kon niet worden gecodeerd.
400	`invalid_pagination`	Parameters voor paginering moeten scalaire waarden zijn.
400	`invalid_offset`	Offset moet een geheel getal van 0 tot 2000 zijn.
400	`invalid_snapshot`	De ID van de momentopname heeft een ongeldig formaat.
400	`snapshot_required`	Een offset groter dan nul vereist een momentopname-ID. Begin met offset=0.
400	`snapshot_mismatch`	De periode, datums of zoekfilter wijken af van het oorspronkelijke verzoek.
410	`snapshot_expired`	De momentopname is verlopen of niet meer beschikbaar voor deze gebruiker/tracker. Begin opnieuw met offset=0 en zonder snapshot.
503	`snapshot_storage_unavailable`	De opslag voor momentopnamen kan niet worden gelezen of beschreven. Probeer opnieuw en behoud een eerder ontvangen ID.
503	`recap_unavailable`	Er kan momenteel geen volledige nieuwe momentopname worden gemaakt. Probeer het binnenkort opnieuw.

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