L'API
 Planète Moteurs

Notre API pour les émissions de CO2 à l'usage de l'automobile

Découvrez notre API RESTful

Notre API REST a pour but de rendre accessible aux développeurs nos données d'émissions de CO2 à l'usage pour l'automobile. Ses endpoints et ses options de filtrage permettent d'accéder aux moyennes d'émissions de CO2 à l'usage de différents types de véhicules, motorisés par différentes technologies, en fonction du profil de conduite.

L'API permet par ailleurs aux utilisateurs d'accéder aux détails de leur profil, ainsi qu'à leurs émissions de CO2 lorsqu'elles ont été enregistrées dans l'outil 'Mon Suivi CO2'.

# Les ressources

L'API propose deux types de ressources principaux :

  • Les émissions de CO2 à l'usage de chaque type de véhicule, en fonction de son carburant, et du type de route emprunté.
    Ces émissions, exprimées en grammes de CO2 par kilomètre parcouru, sont une moyenne de plusieurs véhicules de chaque gamme sur cycle WLTC, dans les conditions spécifiées : carburant (essence, Diesel, hybride essence, hybride Diesel, hybride rechargeable en mode standard, hybride rechargeable en mode recharge, électrique) et type de route (roulage urbain, sur route de campagne, sur autoroute ou mixte). Toutes ces données sont des moyennes calculées sur des véhicules homologués entre 2019 et aujourd'hui, et par définition peuvent varier légèrement d'un véhicule à un autre. Ces données, issues du cycle WLTC réalisé en laboratoire, peuvent également différer des émissions réelles sur route, en fonction notamment des conditions de température, d'altitude, d'usure et autres qui peuvent influer sur la performance générale du véhicule, quelle que soit la technologie utilisée. Enfin, ces données représentent exclusivement les émissions de CO2 estimées lors de l'utilisation du véhicule. Elles ne prennent en compte ni la fabrication du véhicule et de ses composants, ni l'extraction, la transformation ou l'acheminement des ressources primaires, comme le carburant fossile, l'uranium ou le charbon nécessaires à la production d'électricité.
  • Les données personnelles de l'utilisateur authentifié. L'accès à l'API ne doit et ne pourra être effectué que par un utilisateur disposant d'un compte sur notre site web. Il lui sera alors possible de consulter et de mettre à jour un certain nombre de données le concernant via l'API. Ces données personnelles ne seront accessibles qu'à l'utilisateur authentifié, et ne seront en aucun cas disponibles publiquement ou sans authentification préalable.

# L'authentification

Tout accès à l'API ne sera possible qu'en fournissant un token (ou jeton) d'authentification. Celui-ci sera disponible exclusivement aux membres ayant créé un compte et accédé à leur espace personnel sur notre site web.

L'authentification sera effectuée par l'API lors de chaque appel. Celle-ci doit prendre la forme d'un 'Bearer Token' dans l'en-tête (header) de la requête API.

Bearer token dans le header

Comment obtenir un token d'accès à l'API ?

  • #1. Connectez-vous à votre compte Planète-Moteurs, et accédez à votre espace personnel
  • #2. Rejoignez le sous-menu 'Paramètres' de votre espace personnel

    Profile page parameters
  • #3. Dans le sous-menu 'Paramètres', cliquez sur le bouton 'Générer' pour générer un token unique et personnel.
    Generate token button
    Votre token unique et personnel s'affichera alors dans un nouvel encadré dédié.
  • Attention ! Ce token est strictement personnel et ne peut être partagé ni cédé. Celui-ci sera crypté immédiatement pour des raisons de sécurité. Pour cette raison, votre token ne sera visible qu'une seule et unique fois lors de sa création. Il ne sera pas possible de le revoir par la suite. Prenez donc soin de le copier et le sauvegarder dans un endroit sûr et sécurisé.
    Si le token est perdu, il faudra en générer un nouveau (en suivant la même procédure que précédemment), ce qui aura pour effet immédiat de rendre l'ancien token caduque. Il faudra utiliser le nouveau token généré pour s'authentifier lors des nouvelles requêtes sur l'API.

# Les endpoints

Pour les deux ressources disponibles, l'API propose deux familles d'endpoints associées : les endpoints /emissions et les endpoints /user. Pour chacun de ces endpoints, plusieurs actions peuvent être disponibles, et sont décrites ci-dessous.

Pour accéder à chacune de ces ressources, le chemin d'accès complet sera l'adresse du site web, suivi du préfixe /api/, puis de l'URI définie pour chaque ressource.

Par exemple, pour accéder à la ressource 'émissions', l'endpoint complet sera donc :

https://www.planete-moteurs.fr/api/v1/emissions

Pour tous les endpoints, le content-type et le response-type seront de type :
application/json

Les actions, paramètres et réponses typiques de chaque endpoint sont décrits ci-dessous :

# L'endpoint /v1/emissions
  • GET /v1/emissions


    Description générale : Accéder aux émissions de CO2 à l'usage de chaque type de véhicule.

    Verbe GET
    Endpoint /v1/emissions
    Authentification Requise - Bearer token personnel
    Contenu de la ressource Fournit les émissions de CO2 moyennes à l'usage, sur WLTC, par type de véhicule, en fonction de la motorisation et du type de route.
    Paramètres optionnels country :
    Optionnel - type String - Définit le pays dans lequel l'électricité est produite pour les véhicules électriques. Par défaut, le facteur d'émissions moyen de l'Union Européenne sera sélectionné.

    Valeurs disponibles (case-sensitive) :
    • 'France'
    • 'Belgium'
    • 'Germany'
    • 'Luxemburg'
    • 'Poland'

    car_type :
    Optionnel - type String - Filtre les résultats en fonction du type de véhicule.

    Valeurs disponibles (case-sensitive) :
    • 'city-car' (->citadine)
    • 'compact' (->compacte)
    • 'crossover' (->Cross-over ou SUV compact)
    • 'executive' (->berline)
    • 'break' (->break)
    • 'suv' (->SUV ou 4x4)

    fuel_type :
    Optionnel - type String - Filtre les résultats en fonction du type de motorisation.

    Valeurs disponibles (case-sensitive) :
    • 'gasoline' (->moteur essence)
    • 'diesel' (->moteur Diesel)
    • 'hybrid-gasoline' (->moteur hybride classique essence)
    • 'hybrid-diesel' (->moteur hybride classique Diesel)
    • 'plugin-std' (->moteur hybride rechargeable, mode normal)
    • 'plugin-charge' (->moteur hybride rechargeable, mode recharge)
    • 'electric' (->moteur 100% électrique)

    road_type :
    Optionnel - type String - Filtre les résultats en fonction du type de route majoritairement empruntée.

    Valeurs disponibles (case-sensitive) :
    • 'urban' (->roulage ville)
    • 'countryside' (->roulage route de campagne)
    • 'highway' (->roulage autoroutier)
    • 'mixed' (->roulage équilibré)

    Tous les paramètres sont cumulables.
    Codes réponse Requête et réponse valides : 200 - Status OK
    Authentification incorrecte : 401 - Unauthorized
    Nombre d'appels maximal dépassé : 400 - Bad Request
    Contenu de la réponse
    • 'car_type' : type de véhicule - type String
    • 'fuel_type' : type de motorisation - type String
    • 'road_type' : type de route majoritairement empruntée - type String
    • 'co2_emissions' : émissions de CO2 moyennes, en grammes de CO2 par kilomètre - type Integer
    • 'unit' : unité des émissions de CO2 proposées - type String
    Exemple de réponse Requête : GET /v1/emissions?country=France&fuel_type=electric
    Exemple de réponse pour l'endpoint /v1/emissions
# L'endpoint /v1/user
  • GET /v1/user


    Description générale : Accéder aux données personnelles de l'utilisateur authentifié.

    Verbe GET
    Endpoint /v1/user
    Authentification Requise - Bearer token personnel
    Contenu de la ressource Fournit à l'utilisateur authentifié un ensemble de données relatives à son profil.
    Paramètres optionnels Aucun.
    Codes réponse Requête et réponse valides : 200 - Status OK
    Authentification incorrecte : 401 - Unauthorized
    Contenu de la réponse
    • 'first_name' : Prénom de l'utilisateur - type String
    • 'last_name' : Nom de famille de l'utilisateur - type String
    • 'email' : adresse e-mail de l'utilisateur - type String
    • 'remaining_api_calls' : nombre de requêtes API restantes - type Integer
    • 'newsletter_subscription' : abonnement à la newsletter - type Boolean
    • 'saved_cars' : nombre de voitures enregistrées - type Integer
    • 'saved_journeys' : nombre de trajets enregistrés - type Integer
    • 'odometer_saves' : nombre d'enregistrements effectués sur 'Mon Suivi CO2' - type Integer
    • 'co2_since_start' : émissions de CO2 estimées depuis le début des enregistrements de l'utilisateur, sur 'Mon Suivi CO2' - type String
    • 'co2_this_year' : émissions de CO2 estimées depuis le début de l'année en cours de l'utilisateur, sur 'Mon Suivi CO2' - type String
    • 'co2_target' : objectif d'émissions annuelles de CO2 fixé par l'utilisateur - type String
    Exemple de réponse Requête : GET /v1/user
    Exemple de réponse pour l'endpoint /v1/user
  • PUT or PATCH /v1/user


    Description générale : Mettre à jour certaines données personnelles de l'utilisateur authentifié.

    Verbe PUT or PATCH
    Endpoint /v1/user
    Authentification Requise - Bearer token personnel
    Contenu de la ressource Permet à l'utilisateur authentifié de mettre à jour une partie des données relatives à son profil.
    Paramètres de modification Les données à mettre à jour peuvent être transmises de deux façons :
    • Dans le corps (body) de la requête. Ces données doivent alors être envoyées au format x-www-form-urlencoded.
    • En paramètres de la requête.

    Données modifiables :
    • 'first_name' : Prénom de l'utilisateur - Type String
    • 'last_name' : Nom de famille de l'utilisateur - Type String
    • 'email' : E-mail de l'utilisateur. Attention ! Cet e-mail est également votre identifiant lors d'une connexion directe sur le site. Le mot de passe restera inchangé. - Type email
    • 'newsletter' : Accepter ou non de recevoir la newsletter. True ou 1 : accord pour réception. - Type boolean
    Codes réponse Requête et réponse valides : 202 - Accepted
    Authentification incorrecte : 401 - Unauthorized
    Contenu de la réponse 'status' : Message de confirmation de la mise à jour des données.
    Exemple de réponse Requête : PATCH /v1/user
    Exemple de réponse pour l'endpoint /v1/user
  • GET /v1/user/measures


    Description générale : Accéder aux enregistrement de l'utilisateur authentifié dans l'outil 'Mon Suivi CO2'.

    Verbe GET
    Endpoint /v1/user/measures
    Authentification Requise - Bearer token personnel
    Contenu de la ressource Permet à l'utilisateur authentifié d'accéder à l'ensemble de ses enregistrements dans l'outil 'Mon Suivi CO2'.
    Paramètres optionnels year :
    Optionnel - Type Integer - Filtre les enregistrements de l'utilisateur par année. Par défaut, tous les enregistrements de l'utilisateur seront inclus dans la réponse.
    Codes réponse Requête et réponse valides : 200 - Status OK
    Authentification incorrecte : 401 - Unauthorized
    Contenu de la réponse
    • 'measure_id' : L'identifiant unique de la mesure - type Integer
    • 'measure_vehicle' : Le nom du véhicule concerné par la mesure, tel que défini par l'utilisateur - type String
    • 'odometer' : La mesure de l'odomètre fournie par l'utilisateur - type String
    • 'recharge_country' : uniquement dans le cas d'un véhicule électrique. Indique le pays choisi pour la production d'électricité qui a servi à la recharge. - type String
    • 'road_type' : Type de route majoritairement emprunté par l'utilisateur entre cette mesure et la mesure précédente. - type String
    • 'fuel_since_last_measure' : si renseigné par l'utilisateur, indique le volume de carburant ou la charge d'électricité qui ont été consommés entre cette mesure et la précédente. - type String
    Exemple de réponse Requête : GET /v1/user/measures
    Exemple de réponse pour l'endpoint /v1/user/measures
  • DELETE /v1/user/measures/:id


    Description générale : Supprimer un enregistrement de l'utilisateur authentifié, via son identifiant.

    Verbe DELETE
    Endpoint /v1/user/measures/:id
    Authentification Requise - Bearer token personnel
    Contenu de la ressource Permet à l'utilisateur authentifié de supprimer un de ses enregistrements dans l'outil 'Mon Suivi CO2', en l'identifiant par son paramètre 'measure_id'. Ce paramètre est obtenu via la requête GET du même endpoint.
    Identifiant obligatoire id :
    Requis - Type Integer - Détermine l'identifiant unique de la mesure qui doit être supprimée. Cet identifiant est accessible via le paramètre 'measure_id' obtenu via une requête GET /v1/measures.
    Seules les mesures appartenant à l'utilisateur authentifié peuvent être supprimées.

    Avertissement : si aucun identifiant n'est fourni, toutes les mesures de l'utilisateur authentifié seront supprimées de façon permanente !
    Codes réponse Requête et réponse valides : 200 - Status OK
    Mesure non reconnue (identifiant incorrect ou mesure non existante) : 400 - Bad Request
    Authentification incorrecte : 401 - Unauthorized
    Contenu de la réponse 'Status' : Renvoie un message avec le statut de la requête.
    Exemple de réponse Requête : DELETE /v1/user/measures/some_measure_id
    Exemple de réponse pour l'endpoint /v1/user/measures/:id
  • DELETE /v1/user/measures


    Description générale : Supprimer tous les enregistrements de l'utilisateur authentifié.

    Verbe DELETE
    Endpoint /v1/user/measures
    Authentification Requise - Bearer token personnel
    Contenu de la ressource Permet à l'utilisateur authentifié de supprimer tous ses enregistrements dans l'outil 'Mon Suivi CO2', de façon permanente.
    Paramètres Aucun
    Codes réponse Requête et réponse valides : 200 - Status OK
    Authentification incorrecte : 401 - Unauthorized
    Contenu de la réponse 'Status' : Renvoie un message avec le statut de la requête.
    Exemple de réponse Requête : DELETE /v1/user/measures
    Exemple de réponse pour l'endpoint DELETE /v1/user/measures
  • GET /v1/user/co2


    Description générale : Accéder aux émissions de CO2 détaillées de l'utilisateur, mois par mois, pour l'année sélectionnée.

    Verbe GET
    Endpoint /v1/user/co2
    Authentification Requise - Bearer token personnel
    Contenu de la ressource Permet à l'utilisateur authentifié d'obtenir ses émissions de CO2, mois par mois, dans le cas où il utilise l'outil 'Mon Suivi CO2'.
    Paramètres optionnels year :
    Optionnel - Type Integer - Permet de définir l'année pour laquelle les émissions de CO2 sont obtenues. Par défaut, l'année en cours sera utilisée.
    Codes réponse Requête et réponse valides : 200 - Status OK
    Année incorrecte, ou pas de données pour l'année indiquée : 400 - Bad Request
    Authentification incorrecte : 401 - Unauthorized
    Contenu de la réponse
    • 'month' : mois de l'année pour lequel les émissions de CO2 sont fournies - type String
    • 'year' : année pour laquelle les émissions de CO2 sont fournies. Par défaut, l'année en cours si le paramètre 'year' n'est pas spécifié. - type String
    • 'co2_emissions' : émissions de CO2, exprimées en kg de CO2, pour le mois et l'année concernés, calculées à partir des données fournies par l'utilisateur dans l'outil 'Mon Suivi CO2' - type Integer
    • 'unit' : unité pour la mesure de CO2 fournie par le paramètre 'co2_emissions'.
    Exemple de réponse Requête : GET /v1/user/co2
    Exemple de réponse pour l'endpoint GET /v1/user/co2

# Restrictions d'usage

L'utilisation de l'API est ouverte à tous les membres du site https://www.planete-moteurs.fr ayant créé un compte et ayant accédé à leur espace personnel.

Cependant, pour l'endpoint /v1/emissions, le nombre d'appels gratuits est limité à 50. Au-delà de 50 appels, l'accès à l'API sera automatiquement interrompu. Merci de nous contacter directement via le formulaire de contact afin de discuter d'une tarification adaptée à votre besoin.

L'accès à l'endpoint /v1/user dans son ensemble est illimité et gratuit.