Stats API

1 Rýchly štart

1. Vo Visitics otvorte Organizácia → API a vytvorte kľúč; ukáže sa len raz — uložte ho na svoj server.
2. Posielajte ho v hlavičke Authorization každej požiadavky.
3. Vyžiadajte si sekciu prehľadu niektorého zo svojich webov:

curl -H "Authorization: Bearer vtk_…" "https://www.getvisitics.com/api/v1/stats?site=example.com&section=overview&days=30"

API vracia len súhrnné čísla — nikdy IP adresy, odtlačky, obsah formulárov ani prepisy chatov. Polohy nesú atribúciu DB-IP (CC BY 4.0); ponechajte ju pri údajoch.

2 Kľúče a oprávnenia

Kľúč patrí organizácii a iba číta, nič nemení. Pri vytvorení zvolíte jeho oprávnenia, weby, ktoré smie čítať (všetky alebo niektoré), a či má platnosť.

Kľúč patrí na server: API neodpovedá prehliadačom iných stránok (bez CORS). Kľúč nikdy nedávajte do adresy — zostal by v logoch a histórii. Uniknutý kľúč zrušíte jedným klikom a prestane platiť hneď.

3 Limity a cache

Plán určuje počet požiadaviek kľúča za hodinu: Aura 600, Luna 3 000, Cosmos 10 000. Každá odpoveď hovorí, koľko zostáva:

Čísla dneška sa počas dňa menia, predchádzajúce dni zostávajú. Odpoveď si nechajte aspoň minútu a pýtajte sa s If-None-Match — nezmenenú odpoveď netreba posielať znova.

4 Chyby

Chyba prichádza ako problem details (RFC 9457) so strojovým kódom v code a ID požiadavky — uveďte ho, keď nám napíšete.

{
    "type": "https://www.getvisitics.com/developers/api/#error-site_not_found",
    "title": "Site not found",
    "status": 404,
    "detail": "The key has no site example.org.",
    "code": "site_not_found",
    "request_id": "3f9c2a1b7d4e8f60"
}

5 Verzie a zmeny

Verzia 1 sa mení len kompatibilne: môžu pribudnúť polia a parametre, nič sa neodoberie ani nepremenuje. Pole, ktoré nepoznáte, ignorujte. Koniec verzie oznámime 12 mesiacov vopred hlavičkami Deprecation a Sunset a e-mailom vlastníkom kľúčov.

6 GET /sites

The sites the key may read

{
    "data": [
        {
            "domain": "example.com",
            "name": "Example shop",
            "timezone": "Europe/Bratislava",
            "created_at": "2026-10-01T08:15:00Z"
        }
    ]
}

7 GET /sites/{domain}

One site

{
    "data": {
        "domain": "example.com",
        "name": "Example shop",
        "timezone": "Europe/Bratislava",
        "created_at": "2026-10-01T08:15:00Z"
    }
}

8 GET /stats

A section of the dashboard — The numbers of one section for a period, with the previous period of the same length for comparison (`kpi.prev`). The fields are those of the dashboard; new fields may be added.

{
    "site": {
        "domain": "example.com",
        "name": "Example shop"
    },
    "section": "overview",
    "timezone": "Europe/Bratislava",
    "range": {
        "from": "2026-10-16",
        "to": "2026-10-22",
        "days": 7,
        "prev_from": "2026-10-09",
        "prev_to": "2026-10-15",
        "today": "2026-10-22"
    },
    "kpi": {
        "cur": {
            "visitors": 342,
            "views": 762,
            "conversions": 14,
            "bounce_rate": 0.17
        },
        "prev": {
            "visitors": 370,
            "views": 752,
            "conversions": 16,
            "bounce_rate": 0.18
        }
    },
    "series": {
        "dates": [
            "2026-10-16",
            "2026-10-17"
        ],
        "total": [
            58,
            41
        ]
    },
    "pages": [
        {
            "path": "/products/",
            "views": 183,
            "visitors": 153
        }
    ],
    "sources": [
        {
            "source": "Google",
            "channel": "search",
            "visitors": 146
        }
    ]
}

9 GET /realtime

Visitors right now — Visitors in the last 5 minutes and the pages they are on.

{
    "data": {
        "visitors": 16,
        "window_seconds": 300,
        "pages": [
            {
                "path": "/products/",
                "visitors": 5
            }
        ]
    }
}

10 GET /export

A table of a section as CSV or JSON — The rows of one table — for spreadsheets and BI tools. Tables by section: overview: pages, sources, channels, countries; behavior: pages, entries, exits, search, not_found; sources: sources, referrers, campaigns, channels; audience: countries, regions, cities, langs; conversions: events, goal_sources, forms, outbound, downloads; funnels: funnel.steps, funnel.by_channel, funnel.by_device; ux: ux_pages, ux_elements, js_errors; speed: vitals_pages.

source,channel,visitors
Google,search,146