Die AutoRadar-API

In 3 Schritten starten

1. Erstellen Sie einen Schlüssel in Ihrem Entwicklerbereich mit nur den nötigen Rechten. Er wird nur einmal angezeigt.
2. Bewahren Sie ihn serverseitig auf, zum Beispiel in der Umgebungsvariable AUTORADAR_API_KEY.
3. Rufen Sie die API mit dem Header Authorization: Bearer <clé> auf:

curl -s "$AUTORADAR_URL/api/v1/listings/search?make=Volkswagen&model=Golf&fuel=diesel&price_max=20000" \
  -H "Authorization: Bearer $AUTORADAR_API_KEY"

Authentifizierung

• Nur über den Header Authorization: Bearer ar_live_…. Ein Schlüssel in der URL (?api_key=) wird abgelehnt: Er würde in Logs und im Verlauf landen. Widerrufen Sie ihn, falls das passiert.
• Cookies werden von der API nie verwendet: Rufen Sie sie von Ihrem Server aus auf.
• Mögliche Einschränkungen pro Schlüssel: IP-Adressen (oder CIDR-Blöcke) und Browser-Ursprünge. Ohne deklarierten Ursprung wird ein Aufruf aus einem Browser abgelehnt (cors_denied).
• Ein Schlüssel kann jederzeit ablaufen, widerrufen oder ersetzt (rotiert) werden, und zwar in Ihrem Bereich.

Rechte (Scopes)

• search:read — Autos suchen (synchron und asynchron)
• parts:read — Ersatzteile suchen
• listings:read — Details eines Inserats lesen
• market:read — Marktstatistiken lesen
• alerts:write — Suchalarme erstellen und löschen
• webhooks:write — Webhooks verwalten

Ein Endpoint ohne ausreichendes Recht antwortet mit 403 insufficient_scope. Die Endpoints /me und /sources sind mit jedem gültigen Schlüssel erreichbar.

Ratenlimits und Kontingente

Jeder Schlüssel hat ein Limit pro Minute (gleitendes Fenster) und ein Monatskontingent, abhängig von Ihrem Angebot zum Zeitpunkt der Erstellung:

Jede Antwort enthält X-RateLimit-Limit und X-RateLimit-Remaining. Darüber hinaus: 429 mit Retry-After (Sekunden). Beachten Sie dies und warten Sie vor einem erneuten Versuch mit zunehmendem Abstand.

Credits

Einige Endpoints verbrauchen Credits. Sie werden beim Aufruf abgebucht und automatisch zurückerstattet, wenn die Antwort ein Fehler ist:

• API · recherche d'annonces : 1 Credit(s) · Chaque appel GET /api/v1/listings/search
• API · recherche de pièces : 1 Credit(s) · Chaque appel GET /api/v1/parts/search
• API · statistiques de marché : 1 Credit(s) · Chaque appel GET /api/v1/market/models/…
• API · positionnement de prix : 2 Credit(s) · Chaque appel GET /api/v1/market/price-position
• Zusätzlicher Suchalarm : 3 Credit(s) · Jeder Alarm über das in Ihrem Abo inbegriffene Kontingent hinaus

Unzureichendes Guthaben: 402 insufficient_credits. Credits kaufen Sie auf der Seite Credits. GET /me zeigt Ihr Guthaben und die Nutzung des Monats.

Paginierung

Synchrone Suchen liefern data, total und next_cursor. Für die nächste Seite senden Sie genau dieselben Parameter erneut mit ?cursor=<next_cursor> (standardmässig 20 Resultate, limit bis 50). Ein Cursor ist an seine Anfrage gebunden: Mit anderen Parametern wird er abgelehnt (invalid_cursor). Asynchrone Suchen werden mit page und per_page paginiert.

Synchrone und asynchrone Suchen

GET /listings/search und GET /parts/search antworten innert höchstens 8 Sekunden mit den bereits verfügbaren Plattformen. Ist complete auf false, starten Sie eine vollständige Suche mit POST /searches (Antwort 202) und verfolgen Sie sie über GET /searches/{id} oder empfangen Sie den Webhook search.completed.

Credits einer asynchronen Suche: Sie werden beim Start abgebucht (gleicher Tarif wie die synchrone Suche). Sie werden automatisch zurückerstattet, wenn die Suche scheitert, bevor eine Plattform abgefragt wurde (nicht verwertbare Anfrage unusable_query, interner Fehler beim Start), oder wenn Sie sie abbrechen (DELETE /searches/{id}), solange sie noch wartet (queued). Eine bereits gestartete Suche bleibt auch bei Abbruch kostenpflichtig.

# 1. Lancer la recherche complète (202 Accepted)
curl -s -X POST "$AUTORADAR_URL/api/v1/searches" \
  -H "Authorization: Bearer $AUTORADAR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode":"achat","ask":"skoda octavia combi diesel","criteria":{"priceMax":"25000"}}'
# → {"id":"srch_…","status":"queued","url":"/api/v1/searches/srch_…", …}

# 2. Suivre la progression (ou recevoir le webhook « search.completed »)
curl -s "$AUTORADAR_URL/api/v1/searches/srch_…?page=1&per_page=50" -H "Authorization: Bearer $AUTORADAR_API_KEY"

Webhooks

Verfügbare Ereignisse: search.completed, alert.match, price.drop. Jede Zustellung ist signiert (AutoRadar-Signature, HMAC-SHA256): Prüfen Sie die Signatur vor jeder Verarbeitung. Beispiele in Node, Python und PHP: Webhook prüfen.

Fehler

Format: { "error": { "code", "message", "request_id" } }. Geben Sie die request_id an (auch im Header X-Request-Id), wenn Sie uns kontaktieren.

Quellen und Weitergabe

Die API liefert nur Angebote von Websites, deren Vereinbarung die Weitergabe erlaubt (Liste: GET /sources). Jedes Angebot gibt seine Quelle, das Lesedatum und den Link zur Originalanzeige an, die anzuzeigen sind. Die Kontaktdaten von Privatverkäufern werden nie zurückgegeben. Siehe die Nutzungsbedingungen der API.