Datenplattform › API-Dokumentation

Preisdaten-API v1

Die API liefert die öffentlich sichtbaren Angebots- und Preisdaten von CyberSlide als JSON. Basis-URL: https://cyberslide.de/api/v1. Alle Preise in Euro inkl. MwSt.; „Bestpreis“ ist der günstigste Angebotspreis ohne Versand, „Bestpreis inkl. Versand“ der günstigste Gesamtpreis. Zeitangaben in ISO 8601. Die maschinenlesbare Spezifikation: openapi.yaml.

Schnellstart

curl "https://cyberslide.de/api/v1/products?gtin=4006381333931" \
  -H "Authorization: Bearer csd_IHR_SCHLUESSEL"

Authentifizierung

Jede Anfrage braucht einen API-Schlüssel im Header Authorization: Bearer csd_…. Schlüssel in der URL (z. B. ?api_key=) werden mit Status 400 abgelehnt, weil sie in Logs und Browser-Verläufen landen – widerrufen Sie einen solchen Schlüssel. Schlüssel erhalten Sie von uns; Sie können mehrere Schlüssel (z. B. je System) haben und einzeln widerrufen lassen. Wir speichern nur einen Hash, ein verlorener Schlüssel kann nicht wiederhergestellt, nur ersetzt werden.

Der Datenumfang hängt vom Tarif ab: Bei markenbeschränkten Tarifen liefern alle Endpunkte nur Produkte Ihrer freigeschalteten Marken; andere Produkte sind nicht auffindbar (404) bzw. Marken nicht freigeschaltet (403).

Limits & Kontingent

Jeder Tarif hat ein Limit pro Minute und ein monatliches Kontingent (Kalendermonat). Jede Antwort enthält:

X-RateLimit-Limit	Anfragen pro Minute laut Tarif
X-RateLimit-Remaining	verbleibende Anfragen im aktuellen Minutenfenster
X-RateLimit-Reset	Unix-Zeitstempel, ab dem das Fenster wieder frei ist
X-Quota-Limit	Anfragen pro Monat laut Tarif
X-Quota-Remaining	verbleibende Anfragen im laufenden Monat
X-Quota-Reset	Beginn des nächsten Abrechnungsmonats
Retry-After	nur bei 429: Sekunden bis zum nächsten Versuch

Ist ein Limit erreicht, antwortet die API mit 429 (rate_limited bzw. quota_exceeded). Abgelehnte Anfragen zählen nicht zum Kontingent. Bitte cachen Sie Antworten und nutzen Sie für laufende Aktualisierungen den Änderungs-Stream statt alle Produkte regelmäßig neu abzufragen.

Fehler

{ "error": { "code": "quota_exceeded", "message": "…" } }

400	key_in_query	Schlüssel in der URL übergeben
401	unauthenticated	Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen
403	suspended / endpoint_not_in_plan / brand_not_allowed / range_not_in_plan	Zugang gesperrt oder nicht im Tarif enthalten
404	not_found	Ressource existiert nicht oder liegt außerhalb Ihres Datenumfangs
422	validation / invalid_*	ungültige Parameter (Details im Feld errors)
429	rate_limited / quota_exceeded	Limit erreicht

Seitenweise Abfrage

Listen verwenden Cursor: Die Antwort enthält meta.next_cursor; übergeben Sie ihn unverändert als cursor, bis er null ist. Cursor sind stabil, auch wenn zwischendurch Daten hinzukommen.

Endpunkte

GET /products

Produktsuche. Parameter (alle optional, kombinierbar): gtin (EAN/GTIN, 8–14 Ziffern), brand (Slug oder ID), category (ID, inkl. Unterkategorien), q (Titelsuche, mind. 3 Zeichen), limit (1–100, Standard 50), cursor.

{
  "data": [{
    "id": 12345, "gtin": "04006381333931", "ean": "4006381333931", "mpn": "…",
    "title": "…", "brand": { "id": 7, "slug": "marke", "name": "Marke" },
    "category": { "id": 505, "name": "…", "path": "… > …" },
    "best_price": 19.99, "best_total_price": 23.94, "max_price": 29.9,
    "currency": "EUR", "shop_count": 7, "in_stock": true,
    "url": "https://…/preisvergleich/…-12345", "updated_at": "2026-11-13T04:12:00+01:00"
  }],
  "meta": { "per_page": 50, "next_cursor": "eyJ…", "prev_cursor": null },
  "links": { "next": "…", "prev": null }
}

GET /products/{id}

Ein Produkt mit dem jeweils günstigsten Angebot je Shop (lieferbare zuerst, dann nach Gesamtpreis): shop (Name, Domain), price, old_price, shipping_cost (null = unbekannt), total_price, in_stock, condition, delivery, updated_at, last_seen_at (zuletzt im Feed gesehen).

GET /products/{id}/price-history

Tageswerte (min/max/Schlusskurs) des Bestpreises. range = 30d, 90d (Standard), 1y oder all (ältere Monate als Monatswerte, monthly: true). Die maximale Rückschau hängt vom Tarif ab.

GET /brands/{slug}/price-index

Täglicher Median der Bestpreise aller aktiven Produkte der Marke und der Index index = Median des Tages ÷ Median 30 Tage zuvor × 100 (null, solange kein Vergleichswert vorliegt). Parameter days (1–365, Standard 90).

{ "data": { "brand": { … }, "basis": "median_best_price", "compare_days": 30,
  "current": { "day": "2026-11-13", "median_price": 49.9, "products": 812, "index": 97.4 },
  "points": [ … ] } }

GET /categories/{id}/stats

Kennzahlen einer Kategorie inkl. Unterkategorien: Anzahl Produkte und Angebote, Bestpreis-Verteilung (min, p25, Median, p75, max, Durchschnitt), Anteil lieferbar und versandkostenfrei, durchschnittlicher Rabatt, die größten Marken und Preisänderungen der letzten 30 Tage. Bei markenbeschränkten Tarifen enthalten top_brands, own_brands und price_changes_30d nur Ihre Marken; market zeigt die Gesamtkategorie aggregiert.

GET /offers/changes

Alle Änderungen des Bestpreises seit since (Pflicht, ISO 8601, höchstens 30 Tage zurück), älteste zuerst. Optional brand (Slug), limit (1–1000, Standard 500), cursor. new_price: null bedeutet: aktuell kein Angebot. Empfohlen: alle 15–60 Minuten mit dem zuletzt erhaltenen Cursor abfragen.

{ "data": [{ "id": 991, "product_id": 12345, "gtin": "…", "title": "…",
  "old_price": 21.99, "new_price": 19.99, "change_percent": -9.09,
  "shop_count": 7, "changed_at": "2026-11-13T10:05:00+01:00", "url": "…" }],
  "meta": { "since": "…", "next_cursor": "OTkx", "has_more": true } }

Daten & Nutzung

Enthalten sind nur öffentlich angezeigte Angebotsdaten. Nicht enthalten – und nie über die API abrufbar – sind vertrauliche Händlerdaten wie Klicks, Bestellungen, Provisionen oder Konditionen. Die Preise stammen aus Händler-Feeds und können sich jederzeit ändern; sie werden ohne Gewähr bereitgestellt. Es gelten die API-Nutzungsbedingungen (u. a. keine Weitergabe der Rohdaten, Quellenangabe, keine Nutzung für Preisabsprachen oder zur Vorgabe von Wiederverkaufspreisen).

Versionierung: Innerhalb von v1 kommen nur neue Felder und Endpunkte hinzu. Inkompatible Änderungen erscheinen als v2 mit mindestens sechs Monaten Übergangszeit. Fragen: data@cyberslide.de.