Zum Hauptinhalt springen
8 Min. Lesedauer

Echtzeit-Daten API

Greifen Sie auf Live-Besucherzahlen und Echtzeit-Analysedaten über öffentliche JSON-Endpunkte zu. Diese Endpunkte sind für die Anzeige von Live-Statistiken auf Ihrer Website ausgelegt und erfordern keine Authentifizierung.

Übersicht

Echtzeit-Endpunkte bieten:

  • Sofortiger Zugriff - Keine Authentifizierung erforderlich
  • Live-Updates - Daten werden alle 5-30 Sekunden aktualisiert
  • Geringe Latenz - Bereitstellung über Cloudflares globales Edge-Netzwerk
  • CORS aktiviert - Sicher direkt vom Browser aus zu nutzen

Basis-URL

Alle Echtzeit-Endpunkte sind verfügbar unter:

https://api.zenovay.com/e

Live-Besucherzahl

Rufen Sie die aktuelle Anzahl der Besucher auf Ihrer Website ab:

GET/e/live/:trackingCode

Ruft die Live-Besucherzahl ab

RequestBash
curl -X GET 'https://api.zenovay.com/e/live/ZV_XXXXXXXXXXX'
Response (200 OK)JSON
{
"liveCount": 42,
"timestamp": "2025-01-20T14:30:00Z"
}

Antwortfelder:

FeldTypBeschreibung
liveCountZahlAktuelle Online-Besucher (aktiv in den letzten 5 Minuten)
timestampZeichenketteISO 8601 Zeitstempel der Daten

Echtzeit-Analysen

Rufen Sie umfassende Echtzeit-Analysen einschließlich Besucher, Seitenaufrufe und geografische Daten ab:

GET/e/realtime/:websiteId

Ruft Echtzeit-Analysedaten ab

RequestBash
curl -X GET 'https://api.zenovay.com/e/realtime/ws_abc123'
Response (200 OK)JSON
{
"visitors": {
  "current": 42,
  "today": 1234,
  "change": 12.5
},
"pageViews": {
  "current": 156,
  "today": 4567,
  "change": 8.3
},
"countries": [
  { "code": "US", "name": "United States", "count": 18 },
  { "code": "GB", "name": "United Kingdom", "count": 8 },
  { "code": "DE", "name": "Germany", "count": 6 }
],
"topPages": [
  { "path": "/", "visitors": 15 },
  { "path": "/pricing", "visitors": 8 },
  { "path": "/features", "visitors": 5 }
],
"timestamp": "2025-01-20T14:30:00Z"
}

Antwortfelder:

FeldTypBeschreibung
visitors.currentZahlBesucher online jetzt
visitors.todayZahlGesamte eindeutige Besucher heute
visitors.changeZahlProzentuale Änderung gegenüber gestern
pageViews.currentZahlSeitenaufrufe in den letzten 5 Minuten
pageViews.todayZahlGesamte Seitenaufrufe heute
countriesArrayTop-Länder nach aktuellen Besuchern
topPagesArrayTop-Seiten nach aktuellen Besuchern

Besucherstatistiken

Rufen Sie detaillierte Besucherstatistiken einschließlich Absprungrate und Sitzungsdauer ab:

GET/e/stats/:trackingCode

Ruft Besucherstatistiken ab

RequestBash
curl -X GET 'https://api.zenovay.com/e/stats/ZV_XXXXXXXXXXX'
Response (200 OK)JSON
{
"visitors": {
  "live": 42,
  "today": 1234,
  "week": 8765,
  "month": 34521
},
"bounceRate": 0.42,
"avgSessionDuration": 185,
"pagesPerSession": 2.9,
"newVisitorRate": 0.65,
"returningVisitorRate": 0.35,
"timestamp": "2025-01-20T14:30:00Z"
}

Antwortfelder:

FeldTypBeschreibung
visitors.liveZahlAktuelle Online-Besucher
visitors.todayZahlEindeutige Besucher heute
visitors.weekZahlEindeutige Besucher diese Woche
visitors.monthZahlEindeutige Besucher diesen Monat
bounceRateZahlAbsprungrate (0-1)
avgSessionDurationZahlDurchschnittliche Sitzungslänge in Sekunden
pagesPerSessionZahlDurchschnittliche Seiten pro Sitzung
newVisitorRateZahlProzentsatz neuer Besucher
returningVisitorRateZahlProzentsatz wiederkehrender Besucher

Website-Status

Überprüfen Sie, ob das Tracking für eine Website aktiv ist:

GET/e/:trackingCode/status

Überprüft den Tracking-Status

RequestBash
curl -X GET 'https://api.zenovay.com/e/ZV_XXXXXXXXXXX/status'
Response (200 OK)JSON
{
"active": true,
"tracking_code": "ZV_XXXXXXXXXXX",
"domain": "example.com",
"last_event": "2025-01-20T14:29:55Z"
}

JavaScript-Integration

Einfacher Live-Zähler

Zeigen Sie die Live-Besucherzahl auf Ihrer Website an:

Live Visitor CounterJavaScript
class LiveVisitorCounter {
constructor(trackingCode, elementId) {
  this.trackingCode = trackingCode;
  this.element = document.getElementById(elementId);
  this.intervalId = null;
}

async fetchCount() {
  try {
    const response = await fetch(
      `https://api.zenovay.com/e/live/${this.trackingCode}`
    );
    const data = await response.json();
    this.updateDisplay(data.liveCount);
  } catch (error) {
    console.error('Failed to fetch visitor count:', error);
  }
}

updateDisplay(count) {
  if (this.element) {
    this.element.textContent = count.toLocaleString();
    this.element.classList.add('updated');
    setTimeout(() => this.element.classList.remove('updated'), 300);
  }
}

start(intervalMs = 30000) {
  this.fetchCount();
  this.intervalId = setInterval(() => this.fetchCount(), intervalMs);
}

stop() {
  if (this.intervalId) {
    clearInterval(this.intervalId);
  }
}
}

// Usage
const counter = new LiveVisitorCounter('ZV_XXXXXXXXXXX', 'visitor-count');
counter.start();

Echtzeit-Dashboard

Erstellen Sie ein Mini-Analytics-Dashboard:

Real-Time DashboardJavaScript
async function updateDashboard(websiteId) {
try {
  const response = await fetch(
    `https://api.zenovay.com/e/realtime/${websiteId}`
  );
  const data = await response.json();

  // Update visitor counts
  document.getElementById('live-visitors').textContent = data.visitors.current;
  document.getElementById('today-visitors').textContent = data.visitors.today.toLocaleString();

  // Update pageviews
  document.getElementById('live-pageviews').textContent = data.pageViews.current;

  // Update top countries
  const countriesList = document.getElementById('top-countries');
  countriesList.innerHTML = data.countries
    .slice(0, 5)
    .map(c => `<li>${c.name}: ${c.count}</li>`)
    .join('');

  // Update top pages
  const pagesList = document.getElementById('top-pages');
  pagesList.innerHTML = data.topPages
    .slice(0, 5)
    .map(p => `<li>${p.path}: ${p.visitors}</li>`)
    .join('');

} catch (error) {
  console.error('Dashboard update failed:', error);
}
}

// Update every 30 seconds
setInterval(() => updateDashboard('ws_abc123'), 30000);
updateDashboard('ws_abc123');

React Hook

Custom React Hook für Echtzeit-Daten:

useRealtimeAnalytics HookTSX
import { useState, useEffect, useCallback } from 'react';

interface RealtimeData {
visitors: {
  current: number;
  today: number;
  change: number;
};
pageViews: {
  current: number;
  today: number;
  change: number;
};
countries: Array<{ code: string; name: string; count: number }>;
topPages: Array<{ path: string; visitors: number }>;
timestamp: string;
}

function useRealtimeAnalytics(websiteId: string, refreshInterval = 30000) {
const [data, setData] = useState<RealtimeData | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<Error | null>(null);

const fetchData = useCallback(async () => {
  try {
    const response = await fetch(
      `https://api.zenovay.com/e/realtime/${websiteId}`
    );
    if (!response.ok) throw new Error('Failed to fetch');
    const json = await response.json();
    setData(json);
    setError(null);
  } catch (err) {
    setError(err instanceof Error ? err : new Error('Unknown error'));
  } finally {
    setLoading(false);
  }
}, [websiteId]);

useEffect(() => {
  fetchData();
  const interval = setInterval(fetchData, refreshInterval);
  return () => clearInterval(interval);
}, [fetchData, refreshInterval]);

return { data, loading, error, refetch: fetchData };
}

// Usage in component
function AnalyticsDashboard({ websiteId }: { websiteId: string }) {
const { data, loading, error } = useRealtimeAnalytics(websiteId);

if (loading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
if (!data) return null;

return (
  <div className="dashboard">
    <div className="stat">
      <span className="label">Live Visitors</span>
      <span className="value">{data.visitors.current}</span>
    </div>
    <div className="stat">
      <span className="label">Today</span>
      <span className="value">{data.visitors.today.toLocaleString()}</span>
    </div>
  </div>
);
}

Vue Composable

Vue 3 Composable für Echtzeit-Daten:

useRealtimeAnalytics ComposableTypeScript
import { ref, onMounted, onUnmounted } from 'vue';

interface RealtimeData {
visitors: { current: number; today: number; change: number };
pageViews: { current: number; today: number; change: number };
countries: Array<{ code: string; name: string; count: number }>;
topPages: Array<{ path: string; visitors: number }>;
}

export function useRealtimeAnalytics(websiteId: string, refreshInterval = 30000) {
const data = ref<RealtimeData | null>(null);
const loading = ref(true);
const error = ref<Error | null>(null);
let intervalId: number | null = null;

async function fetchData() {
  try {
    const response = await fetch(
      `https://api.zenovay.com/e/realtime/${websiteId}`
    );
    if (!response.ok) throw new Error('Failed to fetch');
    data.value = await response.json();
    error.value = null;
  } catch (err) {
    error.value = err instanceof Error ? err : new Error('Unknown error');
  } finally {
    loading.value = false;
  }
}

onMounted(() => {
  fetchData();
  intervalId = window.setInterval(fetchData, refreshInterval);
});

onUnmounted(() => {
  if (intervalId) clearInterval(intervalId);
});

return { data, loading, error, refetch: fetchData };
}

Ratenbeschränkungen

Echtzeit-Endpunkte haben die folgenden Ratenbeschränkungen:

EndpunktRatenbeschränkungCache TTL
/e/live/:trackingCode1000 Anfragen/Min5 Sekunden
/e/realtime/:websiteId500 Anfragen/Min10 Sekunden
/e/stats/:trackingCode500 Anfragen/Min30 Sekunden
/e/:trackingCode/status100 Anfragen/Min60 Sekunden

Daten werden am Edge zwischengespeichert. Mehrere Anfragen innerhalb des Cache TTL erhalten dieselben Daten, was häufiges Abrufen von Client-seitigem Code sicher macht.

CORS-Konfiguration

Alle Echtzeit-Endpunkte unterstützen CORS und können direkt vom Browser aus aufgerufen werden:

CORS HeadersTEXT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

Fehlerbehandlung

Error Handling ExampleJavaScript
async function fetchWithRetry(url, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
  try {
    const response = await fetch(url);

    if (response.status === 429) {
      // Rate limited - wait and retry
      const retryAfter = response.headers.get('Retry-After') || '60';
      await new Promise(r => setTimeout(r, parseInt(retryAfter) * 1000));
      continue;
    }

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    if (i === maxRetries - 1) throw error;
    // Exponential backoff
    await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
  }
}
}

// Usage
try {
const data = await fetchWithRetry('https://api.zenovay.com/e/live/ZV_XXXXXXXXXXX');
console.log('Live visitors:', data.liveCount);
} catch (error) {
console.error('Failed after retries:', error);
}

Best Practices

  1. Lokal zwischenspeichern - Speichern Sie Daten im Speicher, um unnötige Anfragen während schneller UI-Updates zu vermeiden
  2. Updates drosseln - Lösen Sie UI-Updates nicht schneller aus als die Cache TTL
  3. Offline-Modus handhaben - Zeigen Sie veraltete Daten mit einem Zeitstempel an, wenn das Netzwerk nicht verfügbar ist
  4. Änderungen animieren - Sanfte Übergänge, wenn sich Zahlen ändern, lassen die UI responsiver wirken
  5. Ladezustände anzeigen - Zeigen Sie Skeleton Loader während des anfänglichen Abrufens an

Nächste Schritte

  • Widgets - Vorgefertigte einbettbare Widgets
  • Externe API - Vollständige API mit Authentifizierung
  • Custom Events - Nachverfolgen benutzerdefinierter Benutzeraktionen
War diese Seite hilfreich?