Better doc

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