L'API di AutoRadar

Iniziare in 3 passi

1. Crei una chiave nel suo spazio sviluppatori, con solo i diritti necessari. Viene mostrata una sola volta.
2. La conservi lato server, ad esempio nella variabile d'ambiente AUTORADAR_API_KEY.
3. Chiami l'API con l'intestazione Authorization: Bearer <clé>:

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

Autenticazione

• Solo tramite l'intestazione Authorization: Bearer ar_live_…. Una chiave passata nell'URL (?api_key=) viene rifiutata: finirebbe nei log e nella cronologia. Se succede, la revochi.
• L'API non utilizza mai i cookie: la chiami dal suo server.
• Restrizioni possibili per chiave: indirizzi IP (o blocchi CIDR) e origini del browser. Senza un'origine dichiarata, una chiamata proveniente da un browser viene rifiutata (cors_denied).
• Una chiave può scadere, essere revocata o sostituita (rotazione) in qualsiasi momento dal suo spazio.

Diritti (scope)

• search:read — Cercare auto (sincrona e asincrona)
• parts:read — Cercare ricambi
• listings:read — Leggere il dettaglio di un annuncio
• market:read — Leggere le statistiche di mercato
• alerts:write — Creare ed eliminare avvisi
• webhooks:write — Gestire i webhook

Un endpoint senza diritti sufficienti risponde 403 insufficient_scope. Gli endpoint /me e /sources sono accessibili con qualsiasi chiave valida.

Limiti di frequenza e quote

Ogni chiave ha un limite al minuto (finestra scorrevole) e una quota mensile, in base alla sua offerta al momento della creazione:

Ogni risposta riporta X-RateLimit-Limit e X-RateLimit-Remaining. Oltre il limite: 429 con Retry-After (secondi). Rispetti il valore prima di riprovare, con ritardi crescenti.

Crediti

Alcuni endpoint consumano crediti, addebitati alla chiamata e restituiti automaticamente se la risposta è un errore:

• API · recherche d'annonces : 1 credito/i · Chaque appel GET /api/v1/listings/search
• API · recherche de pièces : 1 credito/i · Chaque appel GET /api/v1/parts/search
• API · statistiques de marché : 1 credito/i · Chaque appel GET /api/v1/market/models/…
• API · positionnement de prix : 2 credito/i · Chaque appel GET /api/v1/market/price-position
• Avviso supplementare : 3 credito/i · Ogni avviso oltre la quota inclusa nella sua offerta

Saldo insufficiente: 402 insufficient_credits. I crediti si acquistano nella pagina Crediti. GET /me restituisce il suo saldo e l'utilizzo del mese.

Paginazione

Le ricerche sincrone restituiscono data, total e next_cursor. Per la pagina successiva, ripeta esattamente gli stessi parametri con ?cursor=<next_cursor> (20 risultati di default, limit fino a 50). Un cursore è legato alla sua richiesta: con altri parametri viene rifiutato (invalid_cursor). Le ricerche asincrone si paginano con page e per_page.

Ricerche sincrone e asincrone

GET /listings/search e GET /parts/search rispondono entro 8 secondi al massimo con i siti già disponibili. Se complete vale false, avvii una ricerca completa con POST /searches (risposta 202), poi la segua con GET /searches/{id} oppure riceva il webhook search.completed.

Crediti di una ricerca asincrona: addebitati all'avvio (stessa tariffa della ricerca sincrona). Vengono restituiti automaticamente se la ricerca fallisce prima di interrogare un sito (richiesta non utilizzabile unusable_query, errore interno all'avvio) o se la annulla (DELETE /searches/{id}) finché è ancora in attesa (queued). Una ricerca già avviata resta dovuta, anche se annullata.

# 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

Eventi disponibili: search.completed, alert.match, price.drop. Ogni invio è firmato (AutoRadar-Signature, HMAC-SHA256): lo verifichi prima di qualsiasi elaborazione. Esempi in Node, Python e PHP: verificare un webhook.

Errori

Formato: { "error": { "code", "message", "request_id" } }. Indichi il request_id (presente anche nell'intestazione X-Request-Id) se ci contatta.

Fonti e ridistribuzione

L'API restituisce solo le offerte dei siti il cui accordo autorizza la ridistribuzione (elenco: GET /sources). Ogni offerta indica la sua fonte, la data di lettura e il link all'annuncio originale, da visualizzare. I recapiti dei venditori privati non vengono mai restituiti. Vedi le condizioni d'uso dell'API.