L'API AutoRadar

Démarrer en 3 étapes

1. Créez une clé dans votre espace développeur, avec seulement les droits nécessaires. Elle n'est affichée qu'une fois.
2. Rangez-la côté serveur, par exemple dans la variable d'environnement AUTORADAR_API_KEY.
3. Appelez l'API avec l'en-tête 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"

Authentification

• Uniquement par l'en-tête Authorization: Bearer ar_live_…. Une clé passée dans l'URL (?api_key=) est refusée : elle finirait dans les journaux et l'historique. Révoquez-la si cela arrive.
• Les cookies ne sont jamais utilisés par l'API : appelez-la depuis votre serveur.
• Restrictions possibles par clé : adresses IP (ou blocs CIDR) et origines navigateur. Sans origine déclarée, un appel venant d'un navigateur est refusé (cors_denied).
• Une clé peut expirer, être révoquée ou être remplacée (rotation) à tout moment depuis votre espace.

Droits (scopes)

• search:read — Rechercher des voitures (synchrone et asynchrone)
• parts:read — Rechercher des pièces
• listings:read — Lire le détail d'une offre
• market:read — Lire les statistiques de marché
• alerts:write — Créer et supprimer des alertes
• webhooks:write — Gérer les webhooks

Un endpoint sans droit suffisant répond 403 insufficient_scope. Les endpoints /me et /sources sont accessibles à toute clé valide.

Limites de débit et quotas

Chaque clé a une limite par minute (fenêtre glissante) et un quota mensuel, selon votre offre au moment de sa création :

Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining. Au-delà : 429 avec Retry-After (secondes). Respectez-le avant de réessayer, avec un délai croissant.

Crédits

Certains endpoints consomment des crédits, débités à l'appel et rendus automatiquement si la réponse est une erreur :

• API · recherche d'annonces : 1 crédit(s) · Chaque appel GET /api/v1/listings/search
• API · recherche de pièces : 1 crédit(s) · Chaque appel GET /api/v1/parts/search
• API · statistiques de marché : 1 crédit(s) · Chaque appel GET /api/v1/market/models/…
• API · positionnement de prix : 2 crédit(s) · Chaque appel GET /api/v1/market/price-position
• Alerte supplémentaire : 3 crédit(s) · Chaque alerte au-delà du quota inclus dans votre offre

Solde insuffisant : 402 insufficient_credits. Les crédits s'achètent sur la page Crédits. GET /me renvoie votre solde et l'usage du mois.

Pagination

Les recherches synchrones renvoient data, total et next_cursor. Pour la page suivante, repassez exactement les mêmes paramètres avec ?cursor=<next_cursor> (20 résultats par défaut, limit jusqu'à 50). Un curseur est lié à sa requête : avec d'autres paramètres, il est refusé (invalid_cursor). Les recherches asynchrones se paginent avec page et per_page.

Recherches synchrones et asynchrones

GET /listings/search et GET /parts/search répondent en 8 secondes au plus avec les sites déjà disponibles. Si complete vaut false, lancez une recherche complète avec POST /searches (réponse 202), puis suivez-la par GET /searches/{id} ou recevez le webhook search.completed.

Crédits d'une recherche asynchrone : débités au lancement (même tarif que la recherche synchrone). Ils sont rendus automatiquement si la recherche échoue avant d'avoir interrogé un site (demande inexploitable unusable_query, erreur interne au départ) ou si vous l'annulez (DELETE /searches/{id}) tant qu'elle est encore en attente (queued). Une recherche déjà lancée reste due, même annulée.

# 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

Événements disponibles : search.completed, alert.match, price.drop. Chaque envoi est signé (AutoRadar-Signature, HMAC-SHA256) : vérifiez-le avant tout traitement. Exemples en Node, Python et PHP : vérifier un webhook.

Erreurs

Format : { "error": { "code", "message", "request_id" } }. Indiquez le request_id (aussi dans l'en-tête X-Request-Id) si vous nous contactez.

Sources et redistribution

L'API ne renvoie que les offres des sites dont l'accord autorise la redistribution (liste : GET /sources). Chaque offre indique sa source, la date de lecture et le lien vers l'annonce d'origine, à afficher. Les coordonnées des vendeurs particuliers ne sont jamais renvoyées. Voir les conditions d'utilisation de l'API.