API Analytics & Données Véhicule

Interrogez le profil analytique complet d'un véhicule par VIN ou plaque d'immatriculation : champs normalisés riches, scores de santé et de risque calculés, séries temporelles kilométrage et propriété, comparatifs marché. Authentification Bearer, limitation de débit configurable.

https://api.vinanalyser.com/v1

Demander un accès Voir les endpoints

Démarrage rapide Authentification Endpoints Schéma de réponse Codes d'erreur Limitation de débit

Démarrage rapide

Générer une clé API

Créez un compte dans le tableau de bord et générez une paire de clés (sandbox + production). Les clés sandbox renvoient des analyses d'exemple réalistes sans consommer de quota.

Envoyer une requête

Authentifiez-vous via l'en-tête Authorization: Bearer et votre X-Analytics-Key, puis envoyez un POST sur /v1/analyses pour lancer votre première analyse et inspecter le schéma de réponse.

Lire les analytics

Les réponses sont du JSON normalisé exposant health_score, risk_index, le bloc metrics et une série temporelle de kilométrage. Lisez les scores pour les indices calculés et metrics pour les signaux sous-jacents.

Authentification

Chaque requête doit porter un en-tête Authorization avec un jeton Bearer valide ainsi que votre en-tête X-Analytics-Key. Les clés expirent au bout de 12 mois et se renouvellent sans interruption depuis le tableau de bord. Chaque clé est rattachée à un niveau de données qui détermine les champs analytiques renvoyés.

Exemple de requête

curl -X GET \
  https://api.vinanalyser.com/v1/analyses/an_7c3d20 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY" \
  -H "Content-Type: application/json"

Jeton Bearer

Passez votre clé API dans l'en-tête Authorization sous forme de jeton Bearer, aux côtés de l'en-tête X-Analytics-Key qui identifie votre espace analytics. Générez et renouvelez les clés depuis votre tableau de bord sans interruption ; le niveau de la clé conditionne l'accès au scoring et aux séries temporelles.

N'exposez jamais les clés API dans le code côté client ni dans les paramètres d'URL. Utilisez des variables d'environnement et un proxy côté serveur.

Endpoints

Cinq endpoints en v1. Tous acceptent et renvoient du JSON. Les requêtes POST exigent un corps JSON valide. La profondeur analytique (scores, comparatifs, séries) évolue avec le paramètre depth et le niveau de données de la clé.

POST/v1/analyses

Lancer une analyse

Lance une analyse complète du véhicule : historique agrégé, health_score et risk_index calculés, séries temporelles propriété et kilométrage, comparatifs marché. Renvoie un objet analyse identifié par un préfixe an_.

Nom	Type	Requis	Description
`vin`	string	Conditionnel	VIN à 17 caractères. Requis si license_plate n'est pas fourni
`license_plate`	string	Conditionnel	Numéro de plaque d'immatriculation. Requis si vin n'est pas fourni
`depth`	string	Non	Profondeur d'analyse : standard (par défaut) ou full, pilotant scores, comparatifs et séries

Par VIN

curl -X POST https://api.vinanalyser.com/v1/analyses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin": "WBA3A5G59DNP26082", "depth": "full"}'

Par plaque

curl -X POST https://api.vinanalyser.com/v1/analyses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"license_plate": "AB-123-CD", "depth": "standard"}'

GET/v1/analyses/{analysis_id}

Récupérer une analyse

Récupère une analyse déjà calculée via son analysis_id, en renvoyant l'objet complet avec scores, metrics, timeseries et le nombre de data_points résolus.

Nom	Type	Requis	Description
`analysis_id`	string	Oui	Identifiant de l'analyse, préfixé an_ (paramètre de chemin)

curl -X GET https://api.vinanalyser.com/v1/analyses/an_7c3d20 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY"

GET/v1/analyses/{analysis_id}/timeseries

Séries temporelles kilométrage & propriété

Renvoie les séries temporelles datées qui alimentent une analyse : relevés du compteur dans le temps et changements de propriétaire, prêts à tracer des courbes de tendance ou à détecter les retours en arrière.

Nom	Type	Requis	Description
`analysis_id`	string	Oui	Identifiant de l'analyse, préfixé an_ (paramètre de chemin)
`metric`	string	Non	Série à renvoyer : mileage (par défaut) ou ownership

curl -X GET "https://api.vinanalyser.com/v1/analyses/an_7c3d20/timeseries?metric=mileage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY"

GET/v1/vehicles/{vin}/score

Score rapide

Endpoint score uniquement : renvoie les derniers health_score et risk_index d'un VIN sans lancer d'analyse complète, idéal pour un tri rapide de parc.

Nom	Type	Requis	Description
`vin`	string	Oui	VIN à 17 caractères (paramètre de chemin)

curl -X GET https://api.vinanalyser.com/v1/vehicles/WBA3A5G59DNP26082/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY"

POST/v1/analyses/batch

Analytics par lot

Soumet un tableau de VIN ou de plaques pour analyse en parallèle, idéal pour scorer un parc ou constituer des jeux de données comparatifs.

Nom	Type	Requis	Description
`identifiers`	array	Oui	Tableau de VIN ou de plaques (max 100 par requête)
`depth`	string	Non	Profondeur d'analyse appliquée à chaque élément : standard (par défaut) ou full

curl -X POST https://api.vinanalyser.com/v1/analyses/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifiers": ["WBA3A5G59DNP26082", "AB-123-CD"], "depth": "standard"}'

Schéma de réponse

Chaque analyse renvoie un objet JSON uniforme. Les champs de premier niveau portent l'analysis_id et les scores calculés, les blocs vehicle et metrics contiennent les signaux, timeseries les points datés et meta la profondeur d'analyse.

200 OK

{
  "analysis_id": "an_7c3d20",
  "vin": "WBA3A5G59DNP26082",
  "scored_at": "2026-03-12T10:04:00Z",
  "health_score": 8.6,
  "risk_index": 0.21,
  "vehicle": {
    "make": "BMW",
    "model": "320d",
    "year": 2019
  },
  "metrics": {
    "mileage_trend": "consistent",
    "accident_severity": "none",
    "ownership_stability": 0.92,
    "market_value": {
      "value": 18400,
      "unit": "EUR"
    }
  },
  "timeseries": [
    { "date": "2021-03", "mileage": 12000 },
    { "date": "2026-01", "mileage": 142350 }
  ],
  "data_points": 8200,
  "meta": {
    "depth": "full"
  }
}

Référence des champs

analysis_idstring

Identifiant unique de l'analyse, préfixé an_.

vinstring

Le numéro VIN analysé, utilisé comme clé d'analyse.

scored_atstring

Horodatage ISO 8601 du calcul des scores.

health_scorefloat

Score de santé global du véhicule calculé, de 0 à 10.

risk_indexfloat

Indice de risque calculé de 0 (faible) à 1 (élevé), agrégeant les signaux d'historique.

vehicleobject

Marque, modèle et année identifiés, servant de base à l'analyse.

metrics.mileage_trendstring

Signal de tendance kilométrique : consistent, irregular ou suspicious.

metrics.ownership_stabilityfloat

Score de stabilité de propriété de 0 à 1, plus élevé signifiant moins de transferts.

metrics.market_valueobject

Valeur de marché estimée avec son unité monétaire.

timeseriesarray

Points de kilométrage datés alimentant les courbes de tendance.

data_pointsinteger

Nombre total de points de données résolus pour cette analyse.

Codes d'erreur

L'API renvoie des codes HTTP standard avec leurs phrases de motif standard. Le corps inclut un objet error avec les champs code, message et detail pour faciliter le débogage de votre intégration.

400

Bad Request

Le corps de requête ou les paramètres sont mal formés ou des champs requis sont manquants.

401

Unauthorized

La clé API est manquante, invalide ou a été révoquée.

403

Forbidden

Le niveau de données de la clé API n'autorise pas l'accès à cet endpoint ou à ce bloc analytique.

404

Not Found

La ressource demandée (analyse, véhicule) est introuvable.

429

Too Many Requests

Limite de débit dépassée. Inspectez les en-têtes X-Analytics-RateLimit et réessayez après la fenêtre de réinitialisation.

500

Server Error

Une erreur interne s'est produite. Réessayez la requête ou contactez le support si elle persiste.

Réponse d'erreur

{
  "status": "error",
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "detail": "The provided API key is invalid
               or has expired."
  }
}

Limitation de débit

La limitation s'applique par clé API via un algorithme à fenêtre glissante. Les quotas évoluent avec le niveau de données. Chaque réponse porte des compteurs en temps réel dans les en-têtes X-Analytics-RateLimit.

300Requêtes / min

10,000Requêtes / jour

20Simultanées

Chaque réponse de l'API inclut des en-têtes X-Analytics-RateLimit pour suivre votre consommation en temps réel.

X-Analytics-RateLimit-LimitNombre maximal de requêtes autorisées par fenêtre.

X-Analytics-RateLimit-RemainingRequêtes restantes dans la fenêtre courante.

X-Analytics-RateLimit-ResetHorodatage Unix de réinitialisation de la limite.

Commencez à développer dès aujourd'hui

Demandez un accès sandbox pour tester l'API analytics en conditions réelles. Le passage en production ne nécessite aucun changement de code.

Demander un accès Voir les endpoints