From 0e59799f05688ff479e677dbd0b2d118d3eb6736 Mon Sep 17 00:00:00 2001 From: "Phyks (Lucas Verney)" Date: Thu, 31 Aug 2017 15:03:19 +0200 Subject: [PATCH] Better doc --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/README.md b/README.md index 3c17753..8fbaca7 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,49 @@ license. * Copy `config.py.example` to `config.py` and set your API key there. * Run `velib.py`. + +## Dumped data + +This script is used to dump the returned data from the Velib API every few +minutes. Dumps are available at https://pub.phyks.me/datasets/velib/. + +The script writes in a new SQLite file every week, put in a different folder +by year, and labelled with the week number. + +Each SQLite file has three tables: + +* A `stations` table, containing "permanent" information about each station + (latitude, longitude, number of stands etc). +* A `stationsstats` table which contains the available number of bikes and + stands at each time, for each station. Not that these data are directly + dumped from the API, hence `updated` field is coming from the API and is a + timestamp in milliseconds. +* A `stationsevents` table keeps tracks of modifications of fields in the + `stations` table. For instance when a mobile station changes position, + `latitude` and `longitude` are updated, or when a station gains new + `stands`, this table keeps track of the changes. + +You should have a look at the `init_db` function (or run `.schema` in the +resulting SQLite database) to have more details about the structure of these +tables, it should be rather self-explicit. + +_Note_: There are currently no ways to explicitly list stations addition / +removal. As the API response always contains the data for all the available +stations, you can find when a station was created (removed) by looking at the +first (last) time a line was added in `stationsstats` table for this station. + + +## Visualization + +The visualization script generates sequences of PNG images from your database +dump. You can then concatenate them in a `x264` movie using `ffmpeg` (or +`avconv`, should be the same command): + +``` +cat *.png | ffmpeg -f image2pipe -framerate 10 -i - output.mp4 +``` + + ## Links * Velib API: https://developer.jcdecaux.com/#/home