Endpoint REST API

GET /v1/sources-history

Složení návštěvnosti v čase: průměrný počet současně aktivních čtenářů v jednotlivých kategoriích zdrojů za poslední hodinu, 24 hodin, dnešek, včerejšek, 7 dní nebo vlastní časové období.

Požadavek

Historie je k dispozici od 16. listopadu 2026

Historie zdrojů se zaznamenává od 16. listopadu 2026 a každý den přibývají nová data. Záznam začal přibližně v 16:00 UTC, takže 16. listopad obsahuje pouze večerní hodiny a jeho denní hodnota není srovnatelná s hodnotami za celé dny. Pokud období sahá před 16. listopad 2026, hodnota from se posune na toto datum a odpověď bude obsahovat upozornění. Pokud období končí před tímto datem, odpověď nebude obsahovat žádné body. Starší časy se nikdy neuvádějí jako nula.

GET https://api.nowmetrix.com/v1/sources-history?site=TRACKER_ID&range=today

Tento endpoint ukazuje, jak se složení návštěvnosti mění v čase. Můžete například zjistit, kdy začala návštěvnost z Google Discover nebo zda je organické vyhledávání slabší než včera. Každý bod obsahuje průměrný počet současně aktivních čtenářů v jednotlivých kategoriích zdrojů v daném čase. Tyto hodnoty nepředstavují počet návštěv ani zobrazení stránek a nesčítejte je za více časových bodů. Celkové hodnoty získáte pomocí /v1/recap nebo /v1/overview. Pro jednotlivé aktuální zdroje, například konkrétní sociální síť nebo newsletter, použijte /v1/sources.

Vyzkoušet v API Playground

Ověřování

Požadavek vyžaduje API klíč v hlavičce Authorization v tomto formátu: Authorization: Bearer nm_YOUR_KEY.

Parametry dotazu

Název Typ Povinné Popis
site string povinné ID trackeru. API klíč musí mít k tomuto trackeru přístup.
range string nepovinné Časové období. Vyberte jednu z možností: 1h (posledních 60 minut, body po 2 minutách), 24h (posledních 24 hodin, body po 10 minutách), today a yesterday (kalendářní den v časovém pásmu trackeru, body po 10 minutách), 7d (dnešek a předchozích 6 dní, hodinové body) nebo custom (vyžaduje start a end). Výchozí hodnota: today.
start string nepovinné První kalendářní den vlastního období ve formátu YYYY-MM-DD v časovém pásmu trackeru. Je povinný při použití range=custom a nelze ho použít s jinými obdobími. Nesmí být v budoucnosti.
end string nepovinné Poslední kalendářní den vlastního období ve formátu YYYY-MM-DD, včetně tohoto dne. Je povinný při použití range=custom. Období může trvat nejvýše 366 dní. Datum ukončení v budoucnosti se zkrátí na aktuální čas. Rozlišení závisí na počtu dní se zaznamenanými daty: až 2 dny s body po 10 minutách, až 31 dní s hodinovými body a delší období s denními body.

Příklad cURL

curl -H "Authorization: Bearer nm_YOUR_KEY" \
  "https://api.nowmetrix.com/v1/sources-history?site=TRACKER_ID&range=today"

Příklad odpovědi

{
  "site": "TRACKER_ID",
  "range": "today",
  "start": null,
  "end": null,
  "timezone": "Europe/Zurich",
  "unit": "avg_concurrent_readers",
  "resolution_minutes": 10,
  "from": "2026-11-18T00:00:00+01:00",
  "to": "2026-11-18T09:24:00+01:00",
  "data_available_from": "2026-11-16",
  "notice": null,
  "updated_at": "2026-11-18T08:24:30+00:00",
  "stale": false,
  "categories": [
    "organic",
    "discover",
    "direct",
    "internal",
    "social",
    "referral",
    "email",
    "ai"
  ],
  "points": [
    {
      "t": "2026-11-18T09:00:00+01:00",
      "total": 412.6,
      "unattributed": 6.4,
      "values": {
        "organic": 96.2,
        "discover": 131.5,
        "direct": 88.1,
        "internal": 41.3,
        "social": 27.9,
        "referral": 12.6,
        "email": 7.2,
        "ai": 1.4
      }
    },
    {
      "t": "2026-11-18T09:10:00+01:00",
      "total": 428.3,
      "unattributed": 5.9,
      "values": {
        "organic": 98.7,
        "discover": 144,
        "direct": 86.4,
        "internal": 42.8,
        "social": 28.5,
        "referral": 12.1,
        "email": 8.6,
        "ai": 1.3
      }
    }
  ]
}

Pole odpovědi

Pole Typ Popis
site string ID trackeru použitého v požadavku.
range string Požadované časové období.
start string|null Požadovaný první den pro range=custom, jinak null.
end string|null Požadovaný poslední den pro range=custom, jinak null.
timezone string Časové pásmo trackeru použité pro kalendářní dny a časová razítka, například Europe/Zurich.
unit string Vždy avg_concurrent_readers: průměrný počet čtenářů aktivních současně v rámci každého bodu.
resolution_minutes integer Délka každého bodu v minutách: 2, 10, 60 nebo 1440 (jeden kalendářní den).
from string Začátek období jako časové razítko ISO 8601 s posunem časového pásma trackeru. Pokud požadované období začíná před data_available_from, posune se na toto datum.
to string Konec období jako časové razítko ISO 8601 s posunem časového pásma. U právě probíhajících období jde o aktuální čas.
data_available_from string První den se zaznamenanou historií zdrojů: 2026-11-16. Záznam začal přibližně v 16:00 UTC, takže jde o neúplný den.
notice object|null Je nastaveno, pokud období sahá před data_available_from, jinak má hodnotu null. Požadavek přesto uspěje se stavovým kódem HTTP 200.
notice.code string partial_history: období začíná dříve, proto se hodnota from posunula a starší dny nemají žádné body. no_history: období končí před zahájením záznamu dat, takže pole points je prázdné.
notice.message string Stručné vysvětlení v angličtině určené do logů nebo k zobrazení.
updated_at string Časové razítko UTC určující, kdy byla historie vypočítána.
stale boolean Pokud je backend historie krátkodobě nedostupný, hodnota true znamená, že se vrací poslední platný výsledek.
categories[] array<string> Všechny kategorie zdrojů v pevném pořadí: organic, discover, direct, internal, social, referral, email, ai. Seznam vždy obsahuje všechny kategorie, i když v některé nebyli žádní čtenáři.
points[] array<object> Body v chronologickém pořadí. Časy, pro které nebyla shromážděna žádná data, se vynechávají, takže mohou vznikat mezery.
points[].t string Začátek bodu jako časové razítko ISO 8601 s posunem časového pásma. Při návratu z letního času na standardní se opakovaná hodina sloučí do jednoho bodu.
points[].total number Průměrný počet současně aktivních čtenářů ze všech zdrojů, zaokrouhlený na jedno desetinné místo.
points[].unattributed number Čtenáři zahrnutí v hodnotě total, které nelze přiřadit ke kategorii. Tato hodnota je v současnosti obvykle 0, takže součet kategorií odpovídá hodnotě total. Podíly vždy počítejte jako hodnotu kategorie dělenou hodnotou total, aby výsledek zůstal správný i v případě nezařazených čtenářů.
points[].values object Průměrný počet současně aktivních čtenářů v jednotlivých kategoriích, označených názvy uvedenými v categories. Kategorie bez čtenářů mají hodnotu 0.

Aktuálnost a ukládání do mezipaměti

Odpovědi se ukládají do mezipaměti samostatně pro každý tracker a časové období: na 60 sekund pro 1h, 24h a today, na 5 minut pro 7d a na 30 minut pro yesterday. Vlastní období se ukládají do mezipaměti podle počátečního a koncového data: na 30 minut, pokud období již skončilo, jinak na 60 sekund při desetiminutovém rozlišení a na 5 minut při hodinovém nebo denním rozlišení. Pokud je backend historie krátkodobě nedostupný, vrátí se poslední platný výsledek s hodnotou stale: true a hlavičkou Warning. Odpověď obsahuje také hlavičku X-NowMetrix-Microcache s hodnotou HIT, MISS nebo STALE.

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 byl zrušen.
403 site_not_authorized API klíč nemá k tomuto trackeru přístup.
429 rate_limit_exceeded Byl překročen limit počtu požadavků.
503 redis_unavailable Backend Realtime je dočasně nedostupný.
400 invalid_range Parametr range musí mít hodnotu 1h, 24h, today, yesterday, 7d nebo custom.
400 invalid_date_range Chybí parametr start nebo end, případně některý z nich neobsahuje platné datum ve formátu YYYY-MM-DD; datum start je po datu end nebo leží v budoucnosti; období přesahuje 366 dní; nebo byly parametry start a end odeslány bez range=custom.
503 source_history_unavailable Historie zdrojů je dočasně nedostupná a v mezipaměti není žádný nedávný výsledek. Opakujte požadavek po uplynutí doby uvedené v hlavičce Retry-After.
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}