Plein-moins-cher API
plein-moins-cher offers a paid API allowing you to retrieve fuel prices charged by service stations in France in real time.
Data relating to data flow
The source of the flow comes from the government site prix-carburants.gouv.fr, which provides data on fuel prices charged by service stations in France in near real time.
The feed is adapted by plein-moins-cher in order to enrich the data set with the Names and Brands of service stations (data not directly available in the official feed).
The flow is recalculated approximately every 10 minutes in order to be as faithful as possible to the price variations practiced by service stations once or several times a day.
Limits of liability
The price information and its date/time of update by fuel, as well as the postal addresses of the points of sale are not transformed: they are returned as provided by the government site.
The names and brands of service stations are also taken from the government site, but do not come from the public feed.
Plein-Moss-Cher is not responsible for any potential inconsistencies in this information.
The latitudes/longitudes can be corrected/adapted by the full-cheaper API because they are inconsistent or inaccurate.
plein-moins-cher is fully dependent on the Open Data service provided by the government website prix-carburants.gouv.fr.
Any temporary unavailability of the data source impacts the service provided by the full-less-expensive API: the last information retrieved is then returned by the API, pending the return of the service.
In the event of a permanent shutdown of the Open Data service by the prix-carburants.gouv.fr website, the plein-moins-cher API will de facto cease to operate.
In this case, any subscription taken out would be closed by plein-moins.cher.
The subscriber cannot make a claim.
The use of the API service provided by plein-moins-cher implies acceptance of these limits of liability.
API Access
- The API is accessible on a fixed URL, secure, and protected by token (a token is a digital token).
- Access is unlimited in time, the API can be requested at any time.
- However, a sliding maximum limit of 10 API calls per minute is activated, in order to protect the server from any malicious traffic that would prevent it from functioning.
- A valid token must be passed as a parameter in order to obtain the price information flow relating to all the stations.
- Your unique and personal token is provided on request, by email to pleinmoinscher@gmail.com
Test Token
- The test token allows you to test the API for free.
- The returned result contains however a random but exact game limited to 50 service stations selected arbitrarily among the thousands of stations available.
Access to testing API: https://api.geodateo.com/fuel/prices/v1?token=test
License price
- A unique private token is provided upon request to pleinmoinscher@gmail.com
- This token can be used free for 1 month, this validity limit being defined from the date of the first use of the token
via the API https://api.geodateo.com/fuel/prices/v1?token=<token>
- A license must be paid to permanently benefit from the service.
- In case of non subscription of license, after 1 month, the token provided is deactivated.
A new request must be made at full-cheaper in order to obtain a new token.
Full-less-expensive will then reserve the right or not to issue a new token.
- The price of the license is set at €39/month, payable by subscription by credit card via the secure Stripe platform.
- The user can stop his subscription at any time via his private Stripe billing portal, the link of which will be provided by email upon subscription.
- Any termination of subscription at the initiative of the subscriber permanently deactivates the token.
- It is up to the subscriber not to disclose this token.
- The subscriber cannot share this token or undersell it.
- Payment is made for the benefit of geodateo, publisher of the plein-moins-cher.fr website
Subscribe API
- 100% secure payment
- Price charged monthly
- 100% transparent, no hidden costs
- You are free to unsubscribe at any time
API Documentation
Request
Access to the API is via the following URL:
https://api.geodateo.com/fuel/prices/v1?token=<token>&format= <format>&disposition=<disposition>
| Parameter |
Required |
Default value |
Possible values |
Description |
| token |
Yes |
- |
Your personal key, or "test" |
Your personal identification key |
| format |
No |
json |
json | csv | xls |
Returned format
json (JavaScript Object Notation): Web Data Interchange Format
csv (Comma-Separated Values): Excel-compatible data format where data is separated by semicolons
xls (Microsoft Excel): Excel data format
|
| disposition |
No |
inline |
inline | attachment |
When the API is called via a web browser (Chrome, Firefox, Edge), determines whether the content is displayed in the page (inline) or returned as an uploaded file (attachment)
Note: the "xls" format imposes the "attachment" mode.
|
With the "test" token, test the result obtained: the API provides real-time price data for a random set of 50 stations.
Test URLs:
- Return to json format
https://api.geodateo.com/fuel/prices/v1?token=test&format=json
(with file attached: https://api.geodateo.com/fuel/prices/v1?token=test&format=json&disposition=attachment)
- Return to csv format
https://api.geodateo.com/fuel/prices/v1?token=test&format=csv
- Return to xls format
https://api.geodateo.com/fuel/prices/v1?token=test&format=xls
Answer
Fuel prices
The information is returned by service station in the following format:
| Attribute |
Description |
Example |
| brand |
Petrol station brand |
Esso |
| name |
Name of the gas station |
Seaside resort |
| postal_address |
Service station mailing address |
14 rue de la Gare |
| postal_code |
Zip code |
24100 |
| city |
City name |
Bergerac |
| department_code |
Department code |
24 |
| department_name |
Department name |
Dordogne |
| region |
Region name |
New Aquitaine |
| latitude |
Geographic latitude, between -90° and +90° |
44.8581250 |
| longitude |
Geographic longitude, between -180° and +180° |
0.48215888 |
| diesel_price |
Diesel price, in Euro |
1.618 |
| diesel_update_date |
Date/time of diesel price update |
2023-07-04 19:10:05 |
| e85_price |
E85 ethanol price, in Euro |
1.049 |
| e85_update_date |
E85 Ethanol Price Update Date/Time |
2023-07-04 09:31:03 |
| e10_price |
Price of Unleaded 95-E10, in Euro |
1.784 |
| e10_update_date |
95-E10 Unleaded Price Update Date/Time |
2023-07-04 19:10:03 |
| sp95_price |
Price of Unleaded 95, in Euro |
1.844 |
| sp95_update_date |
Update date/time
of the price of Unleaded 95 |
2023-07-04 19:22:13 |
| sp98_price |
Price of Unleaded 98, in Euro |
1.774 |
| sp98_update_date |
Unleaded 98 Price Update Date/Time |
2023-07-04 18:18:15 |
| gplc_price |
LPG price, in Euro |
1.884 |
| gplc_update_date |
LPG price update date/time |
2023-07-04 18:07:46 |
Notes:
- attributes in blue are potentially adapted or corrected by full-less-expensive,
- attributes in yellow are added by plein-cheaper (because not present in the official feed),
- the other attributes come directly from the government flow, they are not transformed.
format=csv
Returns a table with header whose data is separated by semicolons
Example:
https://api.geodateo.com/fuel/prices/v1?token=test&format=csv
With attached file:
https://api.geodateo.com/fuel/prices/v1?token=test&format=csv&disposition=attachment
format=xls
Returns a Microsoft Excel compatible file
Example:
https://api.geodateo.com/fuel/prices/v1?token=test&format=xls
format=json
Returns a json structure containing:
| Attribute |
Description |
| date_generated |
Date/Time of stream generation in YYYY-MM-DD H24:MI:SS format, at TimeZone Europe/Paris. Ex: 2023-07-15 21:05:05 |
| items |
An array of objects showing information by gas station |
| context |
"token": the token used,
"date_requested": date/time of stream request in YYYY-MM-DD H24:MI:SS format, at TimeZone Europe/Paris,
"originating_ip": the calling IP,
"token_first_utilisation_date": the date of first usage,
"token_validity": the validity date (date of first use +1 month) or "unlimited" in case of paid license. |
Example:
https://api.geodateo.com/fuel/prices/v1?token=test&format=json
With attached file:
https://api.geodateo.com/fuel/prices/v1?token=test&format=json&disposition=attachment
HTTP Response codes
List of HTTP response codes
| Code |
Description |
| 200 |
OK: request processed successfully, a result is returned. |
| 400 |
Bad request: the URL or one of its parameters is invalid. |
| 401 |
Unauthorized: the token used is invalid. |
| 406 |
Not Acceptable: the client must accept the gzip encoding (Accept-Encoding:gzip must be present in the Header of the request). |
| 429 |
Too many requests: usage limit exceeded. Retry the request later. |
| 500 |
Internal Server Error: An internal server error has occurred. Retry the request later. |
Important note
The client must issue the HTTP request with the header Accept-Encoding:gzip
This header is automatically added when the API is requested via a web browser such as Chrome, Firefox or Edge.
On the other hand, it must be explicitly specified when the API is called from the command line with a tool like curl:
In case of absence, a return with HTTP code 406 (Not acceptable) is generated.
API call, followed by stream decompression:
curl -sH 'Accept-Encoding: gzip' https://api.geodateo.com/fuel/prices/v1?token=TEST | gunzip
