VacantSearch 🏠

The project is live at https://opendatastl.github.io/VacantSearch/ Go check it out!

Backend

Prerequisites

Python 🐍
- Python3 - Python language interpreter
- Pip - Python package manager
- Virtualenv - Python environment manager
Postman - Tool to send API requests and read responses. (Get Postman)
Login credentials to OpenSTL Database - Please contact repo owner for credentials
GitBash - (Get this only if you have Windows operating system)

Installing

Create virtual environment

Create a Python 3 environment. Replace [envname] with an environment name that makes sense.

virtualenv -p python3 [envname]

Once environment is created, run:

For Mac or Linux,

source [envname]/bin/activate

For Windows,

source [envname]/Scripts/activate

In repo directory, run the following command:

pip install -r requirements.txt

Connect to OpenSTL Database

Get access credentials from repo owner -- you will need a username and a password.
Open settings.txt in the top-level directory of the repository with text editor of choice.
Replace [yourUsername] and [yourPassword] with your credentials, then save.

username:[yourUsername]
password:[yourPassword]

(For Developers) Run the following command to ignore changes in settings.txt, so that you don't accidentally commit your user credentials 😛

git update-index --assume-unchanged settings.txt

Example

Open terminal, navigate to server sub-directory.

cd server/

Start the backend server locally using following command:

python vacancy.py

Open Postman (get Postman if you haven't already), create a POST request to http://127.0.0.1:5000/filter with the following example JSON payload:

{
	"Neighborhoods" : [34,13],
	"LotType" : 2,
	"IncludePossible" : true,
	"NumBathsMin" : 0,
	"NumBathsMax" : 3,
	"SqFtMin" : 0,
	"SqFtMax" : 10000,
	"PriceMin" : 0,
	"PriceMax" : 10000
}

The Postman page should look like the following:

You should get a response JSON with vacancy records that matches the criteria specified in the POST request. The response should somewhat resemble this:
You can now try modifying the POST request payload. Here is a detailed explanation of each JSON key means:

Key (filter criteria)	Expected Datatype	Description
Neighborhoods	List of integers	Neighborhoods to include in search Refer to Neighborhood Codes
LotType	Integer values 0,1 or 2	`0` = both vacant lots & building `1` = only vacant lots `2` = only vacant buildings
IncludePossible	Boolean	Whether to include "possible" entries `True` will return data labeled as "possible" lots or buildings
NumBathsMin	Integer	Minimum number of bathrooms
NumBathsMax	Integer	Maximum number of bathrooms
SqFtMin	Float	Minimum square footage
SqFtMax	Float	Maximum square footage
PriceMin	Float	Minimum price
PriceMax	Float	Maximum price

Deployment

🚧 Work in Progress 🚧

Once you got the application to run locally, it is ready to be deployed on a real back-end server!

Move vacancy.service file into systemd directory.

Front-End Integration 🔧

This project includes a stripped-down front-end that makes Ajax calls to the filter API described above.

Use Local Back-end Server

Make sure that the flask application is still running. If not, in the server/ directory, run the following command: following command:

python vacancy.py

Navigate to the Test/ directory in this repository.
(Optional) Open sampleFrontEnd.html in text editor. Find and modify the POST request JSON payload if you'd wish to filter on certain fields.
Double-click on sampleFrontEnd.html. You should see the following webpage: The JSON response is printed on the page. Alternatively, you can also use your favorite web console to examine the response.

Use Deployment Back-end Server

If you don't know the OpenSTL server filter API url, contact repo-owner to obtain it.
Navigate to the Test/ directory in this repository.
Open sampleFrontEnd.html in text editor. Navigate to the script section and modify the url to the OpenSTL server API url.

// !! Replace "127.0.0.1:5000" below with depolyment server hostname
var url = "http://some-api-url/filter";

(Optional) In sampleFrontEnd.html, modify the POST request JSON payload if you'd wish to filter on certain fields.
Double-click on sampleFrontEnd.html. You should see the following webpage: The JSON response is printed on the page. Alternatively, you can also use your favorite web console to examine the response.

aldodelgado/VacantSearch