API plein-moins-cher
plein-moins-cher propose une API payante permettant de récupérer les prix des carburants pratiqués par les stations-service en France en temps réel.
Données relatives au flux de données
La source du flux provient du site gouvernemental prix-carburants.gouv.fr, qui met à disposition les données relatives aux prix des carburants pratiqués par les stations-service en France en quasi temps réel.
Le flux est adapté par plein-moins-cher de façon à enrichir le jeu de données par les Noms et Marques des stations-service (données non directement disponibles dans le flux officiel).
Le flux est recalculé environ toutes les 10 minutes afin d'être le plus fidèle possible aux variations de prix pratiquées par les stations service une à plusieurs fois par jour.
Limites de responsabilité
Les informations de prix et leur Date/heure de mise à jour par carburant, ainsi que les adresses postales des points de vente ne sont pas transformées: elles sont restituées telles que fournies par le site gourvernemental.
Les noms et marques des stations services sont elles aussi récupérées du site gouvernemental, mais ne proviennent pas du flux public.
Plein-moins-cher n'est aucunement responsable de potentielles incohérences en rapport à ces informations.
Les latitudes/longitudes peuvent être corrigées/adaptées par l'API plein-moins-cher car incohérentes ou peu précises.
plein-moins-cher est pleinement dépendant du service Open Data fourni par le site gouvernemental prix-carburants.gouv.fr.
Toute indisponibilité temporaire de la source de données impacte le service rendu par l'API plein-moins-cher: les dernières informations récupérées sont alors renvoyées par l'API, en attendant le retour du service.
En cas d'arrêt définitif du service Open Data de la part du site prix-carburants.gouv.fr, l'API plein-moins-cher cessera de facto de fonctionner.
Dans cete hypothèse, tout abonnement souscrit serait clos par plein-moins.cher.
Le souscripteur ne pourra pas porter réclamation.
L'utilisation du service API fourni par plein-moins-cher vaut acceptation de ces limites de responsablité.
Accès à l'API
- L'API est accessible sur une URL fixe, sécurisée, et protégée par token (un token est un jeton numérique).
- L'accès est illimité dans le temps, l'API peut être sollicitée à tout moment.
- Toutefois, une limite maximale de 10 appels à l'API par minute glissante est activée, afin de protéger le serveur de tout traffic malveillant qui l'empêcherait de fonctionner.
- Un token valide doit être passé en paramètre afin d'obtenir le flux d'informations de prix relatif à l'ensemble des stations.
- Votre token unique et personnel est fourni sur demande, par mail à pleinmoinscher@gmail.com
Token de test
- Le token test permet de tester l'API gratuitement.
- Le resultat retourné contient cependant un jeu aléatoire mais exact limité à 50 stations-service sélectionnées arbitrairement parmi les milliers de stations disponibles.
Accès à l'API de test: https://api.geodateo.com/fuel/prices/v1?token=test
Prix de la license
- Un token unique et privé est fourni sur demande à pleinmoinscher@gmail.com
- Ce token peut-être utilisé gratuitement pendant 1 mois, cette limite de validité étant définie à compter de la date de la première utilisation du token
via l'API https://api.geodateo.com/fuel/prices/v1?token=<token>
- Une license doit être payée pour bénéficier définitivement du service.
- En cas de non souscription de license, après 1 mois, le token fourni est désactivé.
Une nouvelle demande doit être faite à plein-moins-cher afin d'obenir un nouveau token.
Plein-moins-cher se réservera alors le droit ou non de délivrer un nouveau token.
- Le prix de la licence est fixé à 39€/mois, payable par abonnement par carte bancaire via la plateforme sécurisée Stripe.
- L'utilisateur peut stopper son abonnement à tout moment via son portail de facturation Stripe privé, dont le lien sera fourni par mail dès la souscription.
- Tout arrêt d'abonnement à l'initiative du souscripteur désactive définitivement le token.
- Il appartient au souscripteur de ne pas divulguer ce token.
- Le souscripteur ne peut pas partager ce token ou le sous-vendre.
- Le paiement se fait au bénéfice de geodateo, éditeur du site plein-moins-cher.fr
S'abonner à l'API
- Paiement 100% sécurisé
- Prix facturé mensuellement
- 100% transparent, pas de coûts cachés
- Vous êtes libre de vous désabonner à tout moment
Documentation de l'API
Requête
L'accès à l'API se fait par l'URL suivante :
https://api.geodateo.com/fuel/prices/v1?token=<token>&format=<format>&disposition=<disposition>
| Paramètre |
Obligatoire |
Valeur par défaut |
Valeurs possibles |
Description |
| token |
Oui |
- |
Votre clef personnelle, ou "test" |
Votre clef d'identification personnelle |
| format |
Non |
json |
json | csv | xls |
Format retourné
json (JavaScript Object Notation): format d'échange de données Web
csv (Comma-Separated Values): format de données compatible Excel ou les données sont séparées par des points virgules
xls (Microsoft Excel): format de données Excel
|
| disposition |
Non |
inline |
inline | attachment |
Quand l'API est appelée via un navigateur Web (Chrome, Firefox, Edge), détermine si le contenu est affiché dans la page (inline) ou retourné en tant que fichier téléchargé (attachment)
Remarque : le format "xls" impose le mode "attachment".
|
Avec le token "test", testez le résultat obtenu: l'API fournit les données de prix en temps réel pour un jeu aléatoire de 50 stations.
URLs de test:
- Retour au format json
https://api.geodateo.com/fuel/prices/v1?token=test&format=json
(avec fichier attaché: https://api.geodateo.com/fuel/prices/v1?token=test&format=json&disposition=attachment)
- Retour au format csv
https://api.geodateo.com/fuel/prices/v1?token=test&format=csv
- Retour au format xls
https://api.geodateo.com/fuel/prices/v1?token=test&format=xls
Réponse
Prix des carburants
Les informations sont retournées par station-service au format suivant :
| Attribut |
Description |
Exemple |
| brand |
Marque de la station-service |
Esso |
| name |
Nom de la station-service |
Station du bord de mer |
| postal_address |
Addresse postale de la station service |
14 rue de la Gare |
| postal_code |
Code postal |
24100 |
| city |
Nom de la ville |
Bergerac |
| department_code |
Code du département |
24 |
| department_name |
Nom du département |
Dordogne |
| region |
Nom de la région |
Nouvelle-Aquitaine |
| latitude |
Latitude géographique, entre -90° et +90° |
44.8581250 |
| longitude |
Longitude géographique, entre -180° et +180° |
0.48215888 |
| gazole_price |
Prix du Gazole, en Euro |
1.618 |
| gazole_update_date |
Date/heure de mise à jour du prix du Gazole |
2023-07-04 19:10:05 |
| e85_price |
Prix de l'éthanol E85, en Euro |
1.049 |
| e85_update_date |
Date/heure de mise à jour du prix de l'éthanol E85 |
2023-07-04 09:31:03 |
| e10_price |
Prix du Sans Plomb 95-E10, en Euro |
1.784 |
| e10_update_date |
Date/heure de mise à jour du prix du Sans Plomb 95-E10 |
2023-07-04 19:10:03 |
| sp95_price |
Prix du Sans Plomb 95, en Euro |
1.844 |
| sp95_update_date |
Date/heure de mise à jour du prix du Sans Plomb 95 |
2023-07-04 19:22:13 |
| sp98_price |
Prix du Sans Plomb 98, en Euro |
1.774 |
| sp98_update_date |
Date/heure de mise à jour du prix du Sans Plomb 98 |
2023-07-04 18:18:15 |
| gplc_price |
Prix du GPL, en Euro |
1.884 |
| gplc_update_date |
Date/heure de mise à jour du prix du GPL |
2023-07-04 18:07:46 |
Remarques:
- les attributs en bleu sont potentiellement adaptés ou corrigés par plein-moins-cher,
- les attributs en jaune sont ajoutés par plein-moins-cher (car non présents dans le flux officiel),
- les autres attributs sont directement issus du flux gouvernemental, ils ne sont pas transformés.
format=csv
Retourne une table avec en-tête dont les données sont séparées par des points-virgules
Exemple:
https://api.geodateo.com/fuel/prices/v1?token=test&format=csv
Avec fichier attaché:
https://api.geodateo.com/fuel/prices/v1?token=test&format=csv&disposition=attachment
format=xls
Retourne un fichier compatible Microsoft Excel
Exemple:
https://api.geodateo.com/fuel/prices/v1?token=test&format=xls
format=json
Retourne une structure json contenant:
| Attribut |
Description |
| date_generated |
Date/Heure de génétation du flux au format YYYY-MM-DD H24:MI:SS, à la TimeZone Europe/Paris. Ex: 2023-07-15 21:05:05 |
| items |
Un tableau d'objets présentant les informations par station service |
| context |
"token": le token utilisé,
"date_requested": date/Heure de demande du flux au format YYYY-MM-DD H24:MI:SS, à la TimeZone Europe/Paris,
"originating_ip": l'IP appellante,
"token_first_utilisation_date": la date de première utilisation,
"token_validity": la date de validité (date de première utilisation +1 mois) ou "unlimited" en cas de license acquittée. |
Exemple:
https://api.geodateo.com/fuel/prices/v1?token=test&format=json
Avec fichier attaché:
https://api.geodateo.com/fuel/prices/v1?token=test&format=json&disposition=attachment
HTTP Response codes
Liste des codes réponse HTTP
| Code |
Description |
| 200 |
OK: requêre traitée avec succès, un résultat est retourné. |
| 400 |
Bad request: l'URL ou l'un de ses paramètres est invalide. |
| 401 |
Unauthorized: le token utilisé est invalide. |
| 406 |
Not Acceptable: le client doit accepter l'encodage gzip (Accept-Encoding:gzip doit être présent dans le Header de la requête). |
| 429 |
Too many requests: limite d'usage dépassée. Réitérer la requête ultérieurement. |
| 500 |
Internal Server Error: une erreur interne au serveur s'est produite. Réitérer la requête ultérieurement. |
Note importante
Le client doit émettre la requête HTTP avec le header Accept-Encoding:gzip
Cet header est automatiquement ajouté, lorsque l'API est sollicitée via un navigateur Web comme Chrome, Firefox ou Edge.
Par contre, il doit être explicitement spécifié lorsque l'API est appelée en ligne de commande avec un outil comme curl:
En cas d'absence, un retour avec code HTTP 406 (Not acceptable) est généré.
Appel de l'API, suivi de la décompression du flux :
curl -sH 'Accept-Encoding: gzip' https://api.geodateo.com/fuel/prices/v1?token=TEST | gunzip
