README.md 4.53 KB
Newer Older
Phyks's avatar
Phyks committed
1 2 3
Flatisfy
========

4
**PROJECT HAS MOVED: Please use
5 6 7
[Framagit](https://framagit.org/phyks/Flatisfy) to create issues on the
project. You can still create merge requests from either
[Github](https://github.com/phyks/flatisfy) or
Phyks's avatar
Phyks committed
8
[Framagit](https://framagit.org/phyks/Flatisfy).**
9

Phyks's avatar
Phyks committed
10 11
Flatisfy is your new companion to ease your search of a new housing :)

Phyks's avatar
Phyks committed
12 13
<script src="https://liberapay.com/Phyks/widgets/button.js"></script>
<noscript><a href="https://liberapay.com/Phyks/donate"><img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg"></a></noscript>
Phyks's avatar
Phyks committed
14

Phyks's avatar
Phyks committed
15 16 17 18 19
**Note**: This software is under heavy development at the moment, and the
database schema could change at any time. Do not consider it as being
production ready. However, I am currently using it for my own housing search
and it is working fine :)

20
<img src="doc/img/home.png" width="45%"/> <img src="doc/img/home2.png" width="45%"/>
Phyks's avatar
Phyks committed
21

Phyks's avatar
Phyks committed
22
It uses [WebOOB](http://weboob.org/) to get all the housing posts on most of
Phyks's avatar
Phyks committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
the websites offering housings posts, and then offers a bunch of pipelines to
filter and deduplicate the fetched housings.


It can be used as a command-line utility, but also exposes a web API and
visualisation, to browse through the results.


_Note_: It is targeted at French users (due to the currently supported
websites), and in particular at people living close to Paris, as I developped
it for my personal use, and am currently living in Paris :) Any feedback and
merge requests to better support other countries / cities are more than
welcome!

_Note_: In this repository and across the code, I am using the name "flat". I
use it as a placeholder for "housing" and consider both are interchangeable.
This code is not restricted to handling flats only!


## Getting started

44 45
See the [getting started guide](doc/0.getting_started.md). If you want to give
it a try quickly, you can have a look at the [Docker image](doc/2.docker.md).
Phyks's avatar
Phyks committed
46

Phyks's avatar
Phyks committed
47 48 49
Documentation for the whole app is available
[online](https://doc.phyks.me/flatisfy/).

Phyks's avatar
Phyks committed
50 51 52 53

## Documentation

See the [dedicated folder](doc/).
Phyks's avatar
Phyks committed
54 55


56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
## Screenshots

### Home page

Display available flats on a map:
<img src="doc/img/home.png"/>

And list them with the details in a sortable table:
<img src="doc/img/home2.png"/>


### Details page

Uniform display of the flat information in a dedicated page, with the contact etc:

<img src="doc/img/details.png"/>


### Follow flats

Track interesting flats and store them with notes:

<img src="doc/img/followed.png"/>


Phyks's avatar
Phyks committed
81 82 83 84 85 86 87
## OpenData

I am using the following datasets, available under `flatisfy/data_files`,
which covers Paris. If you want to run the script using some other location,
you might have to change these files by matching datasets.

* [LaPoste Hexasmal](https://datanova.legroupe.laposte.fr/explore/dataset/laposte_hexasmal/?disjunctive.code_commune_insee&disjunctive.nom_de_la_commune&disjunctive.code_postal&disjunctive.libell_d_acheminement&disjunctive.ligne_5) for the list of cities and postal codes in France.
88
* [Navitia public transport datasets](https://navitia.opendatasoft.com/explore/?sort=modified&refine.geographicarea=France) for the list of subway/tram/bus stations with their positions in France. These are the `stops_fr-*.txt` files, extracted from the `NTFS` datasets for each region.
Phyks's avatar
Phyks committed
89 90 91 92 93 94 95 96 97 98 99

Both datasets are licensed under the Open Data Commons Open Database License
(ODbL): https://opendatacommons.org/licenses/odbl/.


## License

The content of this repository is licensed under an MIT license, unless
explicitly mentionned otherwise.


Phyks's avatar
Phyks committed
100 101 102 103 104
## Contributing

See the `CONTRIBUTING.md` file for more infos.


Phyks's avatar
Phyks committed
105 106 107 108 109 110 111 112
## API

Your Flatisfy instance is accessible through an API. API documentation is
available
[here](https://doc.phyks.me/flatisfy/flatisfy.web.routes.html#module-flatisfy.web.routes.api).


## Getting help
Phyks's avatar
Phyks committed
113 114 115 116

Feel free to open issues. An IRC channel is available at [irc://irc.freenode.net/flatisfy](irc://irc.freenode.net/flatisfy) as well.


Phyks's avatar
Phyks committed
117 118
## Thanks

Phyks's avatar
Phyks committed
119 120 121
* [WebOOB](http://weboob.org/). Note that this is actually the only and best
  software out there to scrape housing posts online. Using it in Flatisfy does
  not mean the authors of Flatisfy endorse WebOOB authors' views.
Phyks's avatar
Phyks committed
122 123 124 125 126 127
* The OpenData providers listed above!
* Navitia for their really cool public transportation API.
* A lots of Python modules, required for this script (see `requirements.txt`).
* [Kresus](https://framagit.org/bnjbvr/kresus) which gave me part of the
  original idea (at least proved me such software based on scraping can
  achieve a high quality level :)
128
* Current favicon is from [Wikipedia](https://commons.wikimedia.org/wiki/File:Home_Icon.svg)