flatisfy/doc/0.getting_started.md

Getting started

Important: Flatisfy relies on Weboob to fetch housing posts from housing websites. Then, you should install the devel branch and update it regularly, especially if Flatisfy suddenly stops fetching housing posts.

Note: For the moment, it requires this MR on Weboob which has not yet been merged.

TL;DR

An alternative method is available using Docker. See 2.docker.md.

1. Clone the repository.
2. Install required Python modules: pip install -r requirements.txt.
3. Init a configuration file: python -m flatisfy init-config > config.json. Edit it according to your needs (see below).
4. Build the required data files: python -m flatisfy build-data --config config.json.
5. Use it to fetch (and output a filtered JSON list of flats) or import (into an SQLite database, for the web visualization) a list of flats matching your criteria.
6. Install JS libraries and build the webapp: npm install && npm run build:dev (use build:prod in production).
7. Use python -m flatisfy serve --config config.json to serve the web app.

Available commands

The available commands are:

• init-config to generate an empty configuration file, either on the stdin or in the specified file.
• build-data to rebuild OpenData datasets.
• fetch to load and filter housings posts and output a JSON dump.
• filter to filter again the flats in the database (and update their status) according to changes in config. It can also filter a previously fetched list of housings posts, provided as a JSON dump (with a --input argument).
• import to import and filter housing posts into the database.
• serve to serve the built-in webapp with the development server. Do not use in production.

Common arguments

You can pass some command-line arguments to Flatisfy commands, common to all the available commands. These are

• --help/-h to get some help message about the current command.
• --data-dir DIR to overload the data_directory value from config.
• --config CONFIG to use the config file located at CONFIG.
• --passes [0, 1, 2, 3] to overload the passes value from config.
• --max-entries N to overload the max_entries value from config.
• -v to enable verbose output.
• -vv to enable debug output.
• --constraints to specify a list of constraints to use (e.g. to restrict import to a subset of available constraints from the config). This list should be passed as a comma-separated list.

Configuration

List of configuration options:

• data_directory is the directory in which you want data files to be stored. null is the default value and means default XDG location (typically ~/.local/share/flatisfy/)
• max_entries is the maximum number of entries to fetch.
• passes is the number of passes to run on the data. First pass is a basic filtering and using only the informations from the housings list page. Second pass loads any possible information about the filtered flats and does better filtering.
• database is an SQLAlchemy URI to a database file. Defaults to null which means that it will store the database in the default location, in data_directory.
• navitia_api_key is an API token for Navitia which is required to compute travel times.
• modules_path is the path to the Weboob modules. It can be None if you want Weboob to use the locally pip-installed modules (default value).
• port is the port on which the development webserver should be listening (default to 8080).
• host is the host on which the development webserver should be listening (default to 127.0.0.1).
• webserver is a server to use instead of the default Bottle built-in webserver, see Bottle deployment doc.
• backends is a list of Weboob backends to enable. It defaults to any available and supported Weboob backend.

Note: In production, you can either use the serve command with a reliable webserver instead of the default Bottle webserver (specifying a webserver value) or use the wsgi.py script at the root of the repository to use WSGI.

Constraints

You should specify some constraints to filter the resulting housings list, under the constraints key. The available constraints are:

• type is the type of housing you want, either RENT (to rent), SALE (to buy) or SHARING (for a shared housing).

• housing_types is a list of house types you are looking for. Values can be APART (flat), HOUSE, PARKING, LAND, OTHER (everything else) or UNKNOWN (anything which was not matched with one of the previous categories).

• area (in m²), bedrooms, cost (in currency unit), rooms: this is a tuple of (min, max) values, defining an interval in which the value should lie. A null value means that any value is within this bound.

• postal_codes is a list of postal codes. You should include any postal code you want, and especially the postal codes close to the precise location you want.

• time_to is a dictionary of places to compute travel time to them (using public transport, relies on Navitia API). Typically,

  "time_to": {
    "foobar": {
        "gps": [LAT, LNG],
        "time": [min, max]
    }
  }
  

  means that the housings must be between the min and max bounds (possibly null) from the place identified by the GPS coordinates LAT and LNG (latitude and longitude), and we call this place foobar in human-readable form. Beware that time constraints are in seconds.

You can think of constraints as "a set of criterias to filter out flats". You can specify as many constraints as you want, in the configuration file, provided that you name each of them uniquely.

Building the web assets

If you want to build the web assets, you can use npm run build:dev (respectively npm run watch:dev to build continuously and monitor changes in source files). You can use npm run build:prod (npm run watch:prod) to do the same in production mode (with minification etc).