3 Min. Lesedauer

API-Referenz

Die Zenovay API ermöglicht Ihnen, auf Ihre Analysedaten programmgesteuert zuzugreifen.

Authentifizierung

Alle API-Anfragen erfordern Authentifizierung. Die externe API verwendet den Header X-API-Key. API-Schlüssel sind ab dem Pro-Plan verfügbar — erstellen Sie einen aus Einstellungen → Sicherheit → API-Schlüssel im Dashboard.

Authentication HeaderBash

curl -H "X-API-Key: YOUR_API_KEY" \
https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID

Basis-URL

Die Basis-URL der externen API ist:

https://api.zenovay.com/api/external/v1

Rate Limits

Die externe API ist nur bei kostenpflichtigen Plänen verfügbar. Kostenlose Pläne bieten keinen Zugriff auf die programmgesteuerte API.

Plan	Anfragen pro Minute	Monatliches Limit
Free	Kein API-Zugriff	Kein API-Zugriff
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

Rate-Limit-Header sind in allen Antworten enthalten:

X-RateLimit-Limit: Anfragelimit
X-RateLimit-Remaining: Verbleibende Anfragen
X-RateLimit-Reset: Unix-Timestamp für den Limit-Reset

Endpoints

Analytics

GET/analytics/{websiteId}

Analysedaten für eine Website abrufen

Parameter

Parameter	Typ	Erforderlich	Beschreibung
`websiteId`	string	Ja	Website-ID
`range`	string	Nein	Zeitbereich: `24h`, `7d`, `30d`, `90d` (Standard: `7d`)

Response

ResponseJSON

{
"website": {
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "domain": "example.com",
  "name": "My Website"
},
"timeRange": "7d",
"totalVisitors": 1247,
"totalPageViews": 3891,
"bounceRate": 42.3,
"topCountries": [
  {
    "name": "United States",
    "code": "US",
    "visitors": 456,
    "percentage": 36.6
  }
],
"dailyStats": [
  {
    "date": "2025-01-01",
    "visitors": 178,
    "pageViews": 542,
    "bounceRate": 38.2
  }
]
}

Echtzeit-Daten

GET/track/realtime/{websiteId}

Echtzeit-Besucherdaten abrufen

Response

ResponseJSON

{
"count": 23,
"visitors": [
  {
    "id": "visitor-123",
    "country_name": "United States",
    "city": "New York",
    "device_type": "desktop",
    "value_score": 78,
    "visited_at": "2025-01-01T12:34:56Z"
  }
],
"timestamp": "2025-01-01T12:35:00Z"
}

Websites verwalten

GET/websites

Alle Websites auflisten

Response

ResponseJSON

{
"websites": [
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "example.com",
    "name": "My Website",
    "tracking_code": "abc123def456",
    "is_active": true,
    "created_at": "2025-01-01T00:00:00Z"
  }
]
}

POST/websites

Eine neue Website erstellen

Anforderungstext

RequestJSON

{
"domain": "newsite.com",
"name": "My New Website"
}

Response

ResponseJSON

{
"website": {
  "id": "789e0123-e89b-12d3-a456-426614174000",
  "domain": "newsite.com",
  "name": "My New Website",
  "tracking_code": "xyz789abc123",
  "is_active": true,
  "created_at": "2025-01-01T12:00:00Z"
}
}

Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes:

Statuscode	Beschreibung
200	Erfolg
400	Ungültige Anfrage - Ungültige Parameter
401	Nicht autorisiert - Ungültiger API-Schlüssel
403	Verboten - Unzureichende Berechtigungen
404	Nicht gefunden - Ressource existiert nicht
429	Zu viele Anfragen - Rate Limit überschritten
500	Interner Serverfehler

Error ResponseJSON

{
"error": "Website not found",
"message": "The specified website ID does not exist or you don't have access to it"
}

Die API verwenden

Sie können die externe API von jeder Programmiersprache aus mit Standard-HTTP-Anfragen aufrufen:

cURL

curl -X GET "https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID" \
-H "X-API-Key: YOUR_API_KEY"

Bash