API analityki linków: pobieraj statystyki kliknięć kluczem API

API analityki linków Elido to jeden endpoint, GET /v1/workspaces/{workspace_id}/analytics/{report} na https://api.elido.app, uwierzytelniany kluczem API obszaru roboczego. Udostępnia 15 raportów: szeregi czasowe kliknięć, podsumowanie zaangażowania, najpopularniejsze linki, stronicowany kursorem strumień ostatnich kliknięć oraz podziały według kraju, odsyłacza, urządzenia, przeglądarki, hosta i miejsca docelowego. Domyślny zakres dat to ostatnie 30 dni, link_id zawęża dowolny raport do jednego krótkiego linku, a eksport CSV, lejki, kohorty i LTV pozostają w panelu.

To cała odpowiedź, jeśli potrzebny był tylko adres URL. Reszta tego przewodnika to informacje, które chciałbym widzieć od razu na każdej stronie API analityki kliknięć: dokładne parametry, JSON, który dostajesz w odpowiedzi, miejsca, w których zakres dat po cichu działa inaczej, niż można założyć, oraz 30-wierszowy skrypt, który co rano wysyła do Slacka liczby z wczoraj.

Większość osób pobierających dane kliknięć domyka pętlę zaczynającą się od tagowania kampanii, więc jeśli Twoje linki nie mają jeszcze spójnych UTM-ów, najpierw napraw to z pomocą kompletnego śledzenia UTM. Czyste dane wejściowe sprawiają, że statystyki warto pobierać.

Co zwraca API analityki linków

Każdy raport znajduje się pod tą samą ścieżką, a nazwa raportu jest ostatnim segmentem. Nazwy z ukośnikiem (links/top, clicks/recent, breakdown/country) trafiają tam bez kodowania. Poproś o cokolwiek spoza listy dozwolonych raportów, a dostaniesz 404 z unknown analytics report.

Zauważ ostatni wiersz. Raporty regionów i miast opakowują wiersze w points, a nie items, bo każdy wiersz niesie kraj oraz region albo miasto zamiast jednego klucza. Widziałem, jak generyczny parser raz się na tym wyłożył. Raz wystarczy.

Ten sam zestaw raportów zasila API i SDK, narzędzie analityczne serwera MCP oraz operację Get Analytics w węźle n8n, więc to, czego nauczysz się tutaj, przyda się też tam.

Uwierzytelnianie kluczem API obszaru roboczego

Klucze API zaczynają się od elido_ i należą dokładnie do jednego obszaru roboczego. Wyślij klucz jako token bearer:

curl -s "https://api.elido.app/v1/workspaces/4821/analytics/summary" \
  -H "Authorization: Bearer $ELIDO_API_KEY"

Router sprawdza dwie rzeczy przed uruchomieniem dowolnego zapytania: czy klucz należy do obszaru roboczego 4821 oraz czy ma analytics.view. Każda wbudowana rola ma to uprawnienie, włącznie z Viewer. Dlatego dla zadań raportujących utwórz klucz Viewer. Cron raportujący nie ma żadnego powodu, by móc usuwać linki, a klucz Viewer tego nie potrafi. Klucz bez dostępu dostaje 403.

link_id też nie poszerza dostępu. Identyfikator obszaru roboczego w ścieżce jest tym, który został sprawdzony, więc identyfikator linku pożyczony z cudzego obszaru roboczego dopasuje zero wierszy i zwróci pustą listę. To właściwa porażka: nudna i bez wycieków.

Parametry zapytań dla statystyk kliknięć: daty, strefa czasowa, filtry

Sześć parametrów pokrywa prawie każde wywołanie API statystyk krótkich linków, które wykonasz:

• from i to, jako YYYY-MM-DD. Pomiń oba, a dostaniesz 30 dni do teraz. Ustaw tylko to, a from domyślnie będzie 30 dni wcześniej.
• link_id, aby ograniczyć dowolny raport do jednego linku, oraz host, aby ograniczyć go do jednej domeny przekierowań. To wygodne, gdy obszar roboczy obsługuje kilka brandowanych domen.
• interval dla timeseries, hour albo day (domyślnie). Wszystko inne powoduje błąd zapytania.
• limit dla podziałów i list najpopularniejszych wyników, od 1 do 200, domyślnie 50. links/top jest wyjątkiem: zwraca 10, chyba że poprosisz o więcej.

Oto szczegół, który potrafi ugryźć. Obie daty są odczytywane jako północ UTC, a okno obejmuje from, ale kończy się przed to. Dla całego 21 września wyślij from=2026-09-21&to=2026-09-22. Wyślij to=2026-09-21, a z tego dnia nie dostaniesz nic.

Strefa czasowa to drugi taki punkt. Przekaż tz jako nazwę strefy czasowej IANA albo ustaw nagłówek X-User-TZ, a timeseries wyznaczy przedziały godzinowe lub dzienne według czasu lokalnego. Przesuwają się tylko przedziały. Okno from/to nadal jest w UTC, więc berlińskie "wczoraj" wymaga nieco szerszego okna, co obsługuje poniższy skrypt. Literówka typu Europe/Berln zwraca 400 z unknown IANA timezone, co jest lepsze niż po cichu błędny wykres.

curl -s -G "https://api.elido.app/v1/workspaces/4821/analytics/timeseries" \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-22" \
  --data-urlencode "interval=day" \
  --data-urlencode "tz=Europe/Berlin" \
  --data-urlencode "link_id=918273"

Kształty odpowiedzi, pod które możesz pisać kod

Punkt szeregu czasowego niesie ts, znacznik czasu RFC 3339 dla początku przedziału, oraz count. Przedziałów bez kliknięć po prostu nie ma, więc uzupełnij luki samodzielnie przed narysowaniem wykresu, bo inaczej spokojna niedziela zniknie z osi x.

{
  "items": [
    { "ts": "2026-09-19T00:00:00Z", "count": 412 },
    { "ts": "2026-09-21T00:00:00Z", "count": 388 }
  ]
}

Podziały zwracają {"items": [{"key": "DE", "count": 1204}, ...]}, posortowane według liczby. Podsumowanie jest płaskim obiektem:

{
  "total_clicks": 5310,
  "unique_visitors": 3987,
  "returning_visitors": 611,
  "avg_clicks_per_visitor": 1.33,
  "bounce_rate": 0.85
}

Dwie definicje są ważne. Unikalni odwiedzający są liczeni według różnych adresów IP w oknie, więc biuro za jednym łączem liczy się raz. A bounce_rate to ułamek, nie procent: udział unikalnych odwiedzających, którzy kliknęli tylko raz w danym oknie. Nie mówi nic o tym, co stało się na stronie docelowej, dlatego te liczby nigdy nie zgadzają się z sesjami GA4 (wpis kliknięcia a sesje GA4 pokazuje, skąd bierze się różnica). Każda liczba jest odfiltrowana z ruchu botów, zanim do Ciebie trafi. To te same zliczenia, które widzisz w analityce linków Elido.

Stronicowanie ostatnich kliknięć kursorem

clicks/recent to raport API śledzenia linków, który zwraca pojedyncze kliknięcia, od najnowszych. Każdy wiersz ma ts, link_id, slug, host, referer, country_code, device, browser, destination, user_agent i ip. Rozmiar strony wynosi od 1 do 500, domyślnie 100.

Gdy strona wraca pełna, odpowiedź niesie next_cursor. Przekaż go jako ?cursor=, aby pobrać następną, starszą stronę; null oznacza, że dotarłeś do końca okna.

Kursor wskazuje znacznik czasu i identyfikator linku ostatniego wiersza. Dwa kliknięcia w ten sam link w tej samej milisekundzie mogą zrównać się na granicy strony, a najgorszy przypadek to jeden zduplikowany wiersz, nigdy pominięty. Deduplikuj po pełnym wierszu, gdy je zapisujesz. Rzadkie, ale dziesięć wierszy wstawiania jest lepsze niż tłumaczenie finansom błędu o jeden.

Te wiersze zawierają adresy IP i agenty użytkownika, więc są danymi osobowymi. Jeśli kopiujesz je do hurtowni, trzymaj ją w UE i ustaw okres retencji; przewodnik po rezydencji danych w UE dla zespołów marketingu wyjaśnia powód. Do większości raportów wcale nie potrzebujesz surowych wierszy, a dzienny agregat jest lepszy dla wszystkich.

Skrypt codziennego raportu kliknięć do Slacka lub arkusza

Oto zadanie, którego większość osób naprawdę chce: co rano opublikować na kanale wczorajsze kliknięcia i pięć najpopularniejszych linków. Używa tylko standardowej biblioteki Pythona oraz przychodzącego webhooka Slacka.

import datetime as dt, json, os, urllib.parse, urllib.request
from zoneinfo import ZoneInfo

BASE = "https://api.elido.app/v1/workspaces/{ws}/analytics/{report}"
WS, KEY = os.environ["ELIDO_WORKSPACE_ID"], os.environ["ELIDO_API_KEY"]
TZ = ZoneInfo("Europe/Berlin")

def report(name, **params):
    url = BASE.format(ws=WS, report=name) + "?" + urllib.parse.urlencode(params)
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(req, timeout=20) as r:
        return json.load(r)

day = dt.datetime.now(TZ).date() - dt.timedelta(days=1)
# UTC window one day wider on each side, then keep only local hours of `day`
window = {"from": day - dt.timedelta(days=1), "to": day + dt.timedelta(days=2)}
hours = report("timeseries", interval="hour", tz="Europe/Berlin", **window)["items"]
total = sum(p["count"] for p in hours
            if dt.datetime.fromisoformat(p["ts"]).astimezone(TZ).date() == day)

top = report("links/top", limit=5, **{"from": day, "to": day + dt.timedelta(days=1)})
lines = [f"• {l['slug']}: {l['count']}" for l in top["items"]]
text = f"Clicks on {day} (Berlin): {total}\nTop links (UTC day):\n" + "\n".join(lines)

body = json.dumps({"text": text}).encode()
urllib.request.urlopen(urllib.request.Request(
    os.environ["SLACK_WEBHOOK_URL"], data=body,
    headers={"Content-Type": "application/json"}))

Uruchamiaj go z crona o 07:00 czasu lokalnego. Sztuczka z godzinami sprawia, że suma jest prawdziwym dniem berlińskim zamiast dniem UTC; links/top nie ma tz, więc jego ranking pozostaje w dniu UTC, a wiadomość to zaznacza.

Wolisz arkusz? Te same dwa wywołania działają w Google Apps Script z UrlFetchApp i codziennym wyzwalaczem, dopisując jeden wiersz dziennie. To także najtańsza droga do panelu Looker Studio.

Jeśli nadal w każdy poniedziałek przepisujesz liczby ze zrzutów ekranu, daj skryptowi klucz Viewer i odzyskaj poranki.

Co pozostaje tylko w panelu

Zakres dostępny dla klucza API jest tylko do odczytu i celowo węższa niż panel. Tego nie da się uzyskać kluczem:

• Eksport kliknięć CSV (clicks.csv). Przycisk pobierania CSV w panelu jest ścieżką do plików zbiorczych.
• Lejki, kohorty, raport LTV, mapy ciepła czasu i geografii oraz widok jakości ruchu.

Jeśli potrzebujesz tylko pliku trafiającego gdzieś zgodnie z harmonogramem, zaplanowane raporty e-mail w panelu robią to bez kodu. Pełny eksport potrzebny przy zamykaniu konta opisuje tekst o tym, co można wyeksportować z konta krótkich linków i jak sprawdzić, czy eksport jest kompletny. A łączone wywołanie "wszystko dla jednego linku" jeszcze nie istnieje, więc panel per link oznacza jedno żądanie na raport. Szybki start SDK pokazuje, jak uruchamiać je równolegle i stosować backoff po trafieniu w limity szybkości.

Odpytywanie API analityki kliknięć a webhooki dla czasu rzeczywistego

Uczciwa wersja: dziś dane kliknięć są tylko do pobrania. Webhooki Elido wypychają zdarzenia linków i domen, podpisane i ponawiane, ale zdarzenie click.created dla pojedynczego kliknięcia jest w planach i jeszcze nie jest emitowane. Wszystko, co dotyczy kliknięć w czasie rzeczywistym, oznacza odpytywanie clicks/recent.

To mniej bolesne, niż brzmi. Odpytuj co minutę lub dwie, zatrzymaj się, gdy tylko dotrzesz do wiersza, który już masz zapisany, a obciążenie pozostanie małe, bo spokojna minuta to jedna mała strona. Gdy click.created zostanie udostępnione, procedurze obsługi wiersza będzie wszystko jedno, czy przyszedł ze strony wyników, czy z pusha. Ogólne kompromisy opisuje tekst webhooki a odpytywanie w śledzeniu kliknięć, a jeśli decydujesz, które z tych liczb w ogóle zasługują na raport, krótsza lektura to co mierzyć w analityce krótkich linków.

Moja opinia: zacznij od dziennego podsumowania. Prawie każdy zespół, który prosi mnie o kliknięcia w czasie rzeczywistym, jest zadowolony z wczorajszych liczb dostarczonych przed kawą.

Przeczytaj tekst filarowy → Jak śledzić kampanie UTM od początku do końca

Powiązane na blogu

• Szybki start API skracacza URL i SDK - klucze, SDK, limity szybkości i wywołanie tworzenia.
• Węzeł skracacza URL w n8n - te same raporty analityczne w przepływie n8n.
• Webhooki a odpytywanie w śledzeniu kliknięć - wybór wzorca integracji.
• Analityka linków w Looker Studio - zamiana codziennego pobierania w panel.
• Połącz Elido z Claude i Cursor przez MCP - pytanie o statystyki kliknięć zwykłym językiem.