Documentation technique : lire une plaque minéralogique via API

On parle encore souvent de « plaque minéralogique », un héritage de l'époque où l'immatriculation des véhicules relevait du service des Mines. Le vocabulaire a changé, mais le besoin reste le même : à partir des caractères inscrits sur la plaque, retrouver le véhicule et ses caractéristiques.

Cette documentation technique décrit, de manière opérationnelle, comment « lire » une plaque minéralogique via notre API : formats d'entrée, construction de la requête, structure de la réponse, champs essentiels et gestion des erreurs.

Formats de plaque acceptés

L'API accepte les deux systèmes de numérotation en circulation en France.

La plaque peut être envoyée avec ou sans séparateurs. Nous recommandons toutefois de normaliser la saisie côté serveur : majuscules, suppression des espaces, des points et des tirets, puis contrôle par expression régulière. Une saisie invalide ne doit pas déclencher d'appel, afin de préserver votre quota.

Construire la requête

L'API est exposée via RapidAPI. Une requête valide comporte :

• la méthode GET ;
• l'URL https://api-plaque-immatriculation-siv.p.rapidapi.com/get-vehicule-info ;
• le paramètre de requête contenant la plaque ;
• deux en-têtes d'authentification : x-rapidapi-host et x-rapidapi-key.

curl --request GET \
--url 'https://api-plaque-immatriculation-siv.p.rapidapi.com/get-vehicule-info?immatriculation=AB-123-CD' \
--header 'x-rapidapi-host: api-plaque-immatriculation-siv.p.rapidapi.com' \
--header 'x-rapidapi-key: VOTRE_CLE_RAPIDAPI'

Structure de la réponse

La réponse est un objet JSON dont les informations utiles sont regroupées dans data. Les valeurs scalaires sont des chaînes de caractères, y compris les nombres : convertissez-les explicitement si vous devez calculer. Seul le tableau pneus contient des nombres.

{
  "data": {
    "erreur": "",
    "immat": "AA123NC",
    "pays": "FR",
    "marque": "PEUGEOT",
    "modele": "207",
    "modele_en": "207 SW",
    "sra_commercial": "SW 1.6 HDI 90 ACTIVE",
    "date1erCir_fr": "12-05-2009",
    "energieNGC": "DIESEL",
    "puisFisc": "5",
    "puisFiscReelKW": "66 KW",
    "puisFiscReelCH": "90 CH",
    "ccm": "1560 CM3",
    "vin": "VF3WE9HXC9W040029",
    "type_mine": "MPE5214TP747",
    "k_type": "23388",
    "photo_modele": "https://…/photos_modeles/23388.jpg",
    "pneus": [
      { "name": "205/55 R 16", "width": 205, "height": 55, "diameter": 16, "load_index": 91, "speed_index": "V" }
    ]
  },
  "api_version": "V1",
  "message": "",
  "code_erreur": 200
}

La réponse complète contient une soixantaine de champs ; l'extrait ci-dessus montre les plus utilisés.

Le champ code_erreur vaut 200 et le champ erreur est vide lorsque la recherche a abouti. Si code_erreur est différent de 200 ou si erreur contient un message, traitez la réponse comme un échec, même si le code HTTP est 200.

Les champs à connaître en priorité

Sur la centaine de champs disponibles, une dizaine couvre la majorité des usages :

• marque, modele, sra_commercial : l'identité commerciale du véhicule, à afficher à l'utilisateur pour confirmation.
• date1erCir_fr / date1erCir_us : la date de première mise en circulation, utile pour l'âge du véhicule.
• energieNGC : le carburant ou la source d'énergie (DIESEL, ESSENCE, ÉLECTRIQUE…).
• puisFiscReelKW / puisFiscReelCH : la puissance réelle en kW et en chevaux.
• puisFisc : la puissance administrative, base du calcul de la carte grise.
• vin : le numéro de châssis, identifiant unique et stable.
• k_type : l'identifiant TecDoc pour la compatibilité des pièces.
• co2 : les émissions en g/km, utiles pour le malus ou la vignette (peut être vide).
• pneus : les dimensions de pneus homologuées, prêtes à afficher.

La liste complète est disponible dans la référence de l'API.

Codes d'erreur et comportements attendus

Appliquez un délai d'expiration de 10 secondes et ne multipliez pas les nouvelles tentatives automatiques : une seule suffit.

Valeurs manquantes et normalisation

Selon l'âge et le type de véhicule, certains champs peuvent être absents, vides ou valoir INCONNU. Votre code doit le prévoir : affichez un tiret plutôt qu'une valeur technique, et ne bloquez pas le parcours pour un champ secondaire manquant. Pour les unités, notez que certaines valeurs incluent leur unité ("1741 KG", "66 KW") : extrayez la partie numérique si nécessaire.

Conclusion

Lire une plaque minéralogique via API repose sur trois étapes : normaliser la saisie, appeler l'endpoint avec les bons en-têtes, puis exploiter l'objet data en gérant proprement les erreurs et les valeurs manquantes. Avec cette documentation, vous avez tout pour passer du test à la production.

FAQ

Faut-il envoyer la plaque avec des tirets ?

Ce n'est pas obligatoire, mais nous recommandons de normaliser la saisie avant l'appel pour garantir un comportement homogène.

Les valeurs numériques sont-elles des nombres ?

Non, les valeurs de la fiche véhicule sont renvoyées sous forme de chaînes (seul le tableau pneus contient des nombres). Convertissez-les explicitement dans votre code.

Où trouver la liste complète des champs ?

Dans la documentation complète, avec le type, un exemple et la description de chaque champ.