Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/traxys/fioul
Tools to fetch & parse french gas station informations
https://github.com/traxys/fioul
Last synced: 9 days ago
JSON representation
Tools to fetch & parse french gas station informations
- Host: GitHub
- URL: https://github.com/traxys/fioul
- Owner: traxys
- Created: 2023-10-28T13:41:08.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2023-11-24T23:49:00.000Z (about 1 year ago)
- Last Synced: 2024-12-21T02:07:47.332Z (15 days ago)
- Language: Rust
- Size: 146 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# fioul
Fioul is a set of programs to interact with French gas station informations.
The dataset is provided [by the government](https://www.prix-carburants.gouv.fr/rubrique/opendata/), as an XML file.
This repository contains a library ([fioul](./fioul)) to fetch and/or parse the data into memory.
It also provides a server ([fioul-server](./server)) to provide the data in an easier format.
A CLI tool ([fioul-cli](./cli)) is provided to query the server easily.
## Server
The server provides a single HTTP route that returns data as a JSON document: `/api/stations`
The server caches the government data, only fetching it once every 5 minutes for instantaneous data and once every 30 minutes for all other sources.
It also caches failure to get the data for 1 hour.
The response is of the form:
```json
{
"status": "ok",
"stations": [],
}
```
Or in case of an error:
```json
{
"status": "error",
"code": 0,
"message": ""
}
```
There are a number of query parameters that can be supplied:
- `source`: One of `instant`, `current_day`, `current_year`, `historic_day`, `historic_year`.
This parameter allows to specify the source of data. Some variants require additional parameters.
- `year`: Specify the year for `historic_day` or `historic_year`
- `month`: Specify the month for `historic_month`
- `day`: Specify the day for `historic_day`
- `location`: Takes a value of the form `latitude,longitude,distance` (with distance in meters) and
returns only the stations closer than `distance` of the `latitude,longitude`.
- `location_keep_unknown`: One of `true` or `false`. Some stations don't have geographic coordinates.
Those are excluded from a `location` search by default, but if this parameter is true they will be
included.
- `ids`: Comma separated list of integer ids of stations, allows to query only specific stations.
## CLI
The CLI can query a fioul server for information. It can also use [nominatim](https://nominatim.org/)
to fetch extra information.
It is recommended to use a self-hosted nominatim instance, as doing `fioul near` can generate a
lot of queries, that will not be compliant with nominatim usage requirements (even if they are
cached once done).
The CLI can be configured by placing a file in `~/.config/fioul/config.toml`.
An [example configuration](./config.toml) is provided, with all the possible options.
## Grafana Dashboard
It's quite easy to integrate fioul with grafana to display prices for a fuel in a bar gauge.
A JSON API data source can be setup, pointing to `http://[*].price`
Then a transform `Rows to fields` needs to be added, setting `id` as the Field name and `price` as the field value.
Labels can be added by overriding the display name of the ids