niqjohnson / owning-a-home-api

The API that drives the Owning A Home project.

Owning a Home API

This provides an API for the Owning a Home project. The tool will return rates available on the market. Note that it relies on bringing data from an external (not free) source.

Status

The API is at version 0.9.6, a work in progress.

Dependencies

• Python 2.6
• virtualenv
• Django 1.6
• Django Rest Framework
• Django localflavor
• MySQL Python
• South
• django-cors-headers
• MySQL
• Homebrew
• pip

Installing and using it locally

The tool is a Django module and can be installed and run inside a Django project.

These instructons assume that you are using a Mac with OS X Yosemite and with Homebrew installed:

###Install required components

####MySQL Install MySQL if you do not have it:

brew install mysql

Start the MySQL Server, this command may need to be run again (if stopped) when trying to bring up the web server later:

mysql.server start

Set Password for root:

mysql_secure_installation

Connect to MySQL with root and password:

mysql -uroot -p

Then create an owning-a-home database:

create database oah;

If you would like to connect with a different user other than root, you can create a user, and replace oah_user with your desired username and password with your desired password:

create user 'oah_user'@'localhost' identified by 'password';
grant all privileges on oah.* to 'oah_user'@'localhost';
flush privileges;
exit

You can now connect to MySQL with your newly created username and password and have access to oah:

mysql -u oah_user -p
# enter your password
show databases;
use oah;
exit

####Django Project It is recommended that you use a virtualenv to keep your dependencies organized:

mkvirtualenv oah
workon oah

Create a folder for your Django project in a workspace or other location you like (~/workspace in this case):

cd ~/workspace
pip install django==1.6
# Create a sample project
django-admin.py startproject oah_api
cd oah_api

Edit oah_api/settings.py to use MySQL as the database, edit the DATABASES dictionary to the following, and replace the database user name and password (or root if you did not create one) you created above:

DATABASES = {
    'default': {
           'ENGINE': 'django.db.backends.mysql',
           'NAME': 'oah',
           'USER': 'oah_user',
           'PASSWORD': 'password',
   }
}

Install mysql-python module:

pip install mysql-python

Sync the database and make sure it can be run and accessed in a browser (http://127.0.0.1:8000) (you may get an error if your MySQL Server is not running, if that's the case, run mysql.server start and try the following again:

python manage.py syncdb
python manage.py runserver

####Owning-A-Home API Module Now you are ready to install the app/module:

Go back to your workspace (~/workspace in the case above) or the location you installed oah_api, please do not clone inside oah_api folder:

cd ~/workspace

Clone and install requirements from the app in virtualenv oah created above:

git clone https://github.com/cfpb/owning-a-home-api
pip install -e owning-a-home-api
cd owning-a-home-api && pip install -r requirements.txt

Back to Django project you created earlier:

cd ~/workspace/oah_api

Add the apps from owning-a-home-api to your Django project you created earlier in INSTALLED_APPS dictionary from oah_api/settings.py:

INSTALLED_APPS += (
    ...
    'rest_framework',
    'countylimits',
    'ratechecker',
    'mortgageinsurance'
    'south',
)

Also add the following urls to your core Django project oah_api/urls.py:

    url(r'^oah-api/rates/', include('ratechecker.urls')),
    url(r'^oah-api/county/', include('countylimits.urls')),
    url(r'^oah-api/mortgage-insurance/', include('mortgageinsurance.urls')),

Sync and migrate the Database:

python manage.py syncdb
python manage.py migrate

You can now start the app again to make sure it is accessible in a browser (http://127.0.0.1:8000):

python manage.py runserver

####Data We only supply county limits data as those are open to the public, we do not supply rate checker or mortgage insurance data.

Loading county limits data:

python manage.py load_county_limits ~/workspace/owning-a-home-api/data/county_limit_data-flat.csv --confirm=y

##What the app does

Owning a Home API includes three Django apps:

####ratechecker This app exposes a single API endpoint, /oah-api/rates/rate-checker and /oah-api/rates/rate-checker-fees, with the following parameters:

Param name	Description	Required	Default value	Acceptable values (values = description)
arm_type	The type of ARM	No, unless rate_structure=arm	N/A	3-1 = 3/1 ARM, 5-1 = 5/1 ARM, 7-1 = 7/1 ARM, 10-1 = 10/1 ARM
institution	The institution name	No	N/A	any valid institution name, for ex. BANKA, BANKB, etc.
io	Interest only flag -- only applicable to ARM loans	No	0	0 = false, 1 = true, blank
loan_amount	The amount of the loan	Yes	N/A	any positive integer
loan_purpose	The purpose of the loan	No	PURCH	PURCH = New Purchase, REFI = Refinance
loan_term	The loan term (years)	Yes	N/A	30, 15
loan_type	The type of loan	Yes	N/A	JUMBO = Jumbo Loan, CONF = Conventional Loan, AGENCY = Agency Loan, FHA = Federal Housing Administration Loan, VA = Veteran Affairs Loan, VA-HB = Veteran Affairs High Balance Loan, FHA-HB = Federal Housing Administration High Balance Loan
lock	Rate lock period	No	60	Typically, 30, 45, or 60. One lender in the database has non-standard rate lock periods, so the code converts a single number to a range: <= 30; >30 and <=45; >45 and <= 60 respectively
ltv *1	Loan to value	No	N/A	Calculated by dividing the loan amount by the house price
maxfico	The maximum FICO score	Yes	N/A	0 - 850. In practice, <600 will return no results. For optimal functioning, MinFICO and MaxFICO should be coordinated. Either, they should be the same value, thereby providing a point estimate of the FICO score, or they should be configured to provide a 20-point range, eg, 700-719. Ranges should be specified to start on an even 20 multiple and end on a 19, 39, 59, etc., except for the top bucket which is 840-850.
minfico	The minimum FICO score	Yes	N/A	0 - 850, see maxfico for more info.
points	Points	No	0	This number is used as the centroid of a range, +/- 0.5, to constrain the results. Input could be any decimal roughly within -4 to +4, but in practice anything outside of -2 to +3 is likely to have few results.
price	The price of the property	Yes	N/A	In general, should be larger than the loan_amount.
property_type	The property type	No	SF	SF = Single Family; CONDO = Condominium; COOP = Housing Cooperative (co-op)
rate_structure	The rate structure of the loan	Yes	N/A	FIXED = Fixed Rate, ARM = Adjusted Rate Mortgage
state	The US state	Yes	N/A	all the US state's abbreviations

*1: We actually calculate its value and don't check the value sent in request

ratechecker will return a JSON object containing data and timestamp, it will also contain fees field when requesting /oah-api/rates/rate-checker-fees.

ratechecker has a management command, load_daily_data, which loads daily interest rate data from CSV.

####countylimits This app exposes a single API endpoint, /oah-api/county, which requires a state parameter for querying Federal Housing Administration loan lending limit, Government-Sponsored Enterprises mortgage loan limit and the Department of Veterans Affairs loan guaranty program limit for the counties in a given state.

Param name	Description	Required	Default value	Acceptable values
state	The US state	Yes	N/A	all the US state's abbreviations or fips codes

countylimits will return a JSON object containing state, county, complete_fips, gse_limit, fha_limit, and va_limit.

countylimits has a management command, load_county_limits, which loads these limits from a CSV file provided in data/county_limit_data-flat.csv

####mortgageinsurance This app exposes a single API endpoint, /oah-api/mortgage-insurance, with the following parameters:

Param name	Description	Required	Default value	Acceptable values (values = description)
arm_type	The type of ARM	No, unless rate_structure=arm	N/A	3-1 = 3/1 ARM, 5-1 = 5/1 ARM, 7-1 = 7/1 ARM, 10-1 = 10/1 ARM
loan_amount	The amount of the loan	Yes	N/A	any positive integer
loan_term	The loan term (years)	Yes	N/A	30, 15
loan_type	The type of loan	Yes	N/A	JUMBO = Jumbo Loan, CONF = Conventional Loan, AGENCY = Agency Loan, FHA = Federal Housing Administration Loan, VA = Veteran Affairs Loan, VA-HB = Veteran Affairs High Balance Loan, FHA-HB = Federal Housing Administration High Balance Loan
maxfico	The maximum FICO score	Yes	N/A	0 - 850. In practice, <600 will return no results. For optimal functioning, MinFICO and MaxFICO should be coordinated. Either, they should be the same value, thereby providing a point estimate of the FICO score, or they should be configured to provide a 20-point range, eg, 700-719. Ranges should be specified to start on an even 20 multiple and end on a 19, 39, 59, etc., except for the top bucket which is 840-850.
minfico	The minimum FICO score	Yes	N/A	0 - 850, see maxfico for more info.
price	The price of the property	Yes	N/A	In general, should be larger than the loan_amount.
rate_structure	The rate structure of the loan	Yes	N/A	FIXED = Fixed Rate, ARM = Adjusted Rate Mortgage
va_status	The Veteran Status	No, unless loan_type=va or va-hb	N/A	DISABLED = Veteran with Disablility RES-NG = Reserve or National Guard REGULAR = Regular
va_first_use	Is this the first time using VA loan?	No, unless loan_type=va or va-hb	N/A	1 = True 0 = False

mortgageinsurance will return a JSON object containing data and request. Data will contain monthly for monthly average premium in percentages (it is an average premium calculated based on premium from all insurers), and upfront for upfront premium in percentage. No data will be returned if no premium were found. Request will be the parameter list.

mortgageinsurance has a management command, load_mortgage_insurance, which loads monthly and upfront data from two CSV files.

Testing

Testing requires mock, you can install it by running the following from your owning-a-home-api folder (preferably within the virtual environment you set up for this project):

pip install -r requirements-test.txt

You can either run each app individually in your oah_api folder:

./manage.py test ratechecker
./manage.py test countylimits
./manage.py test mortgageinsurance

or you can run them together in a standalone test in your owning-a-home-api folder:

python test_standalone.py

Contributions

We welcome contributions with the understanding that you are contributing to a project that is in the public domain, and anything you contribute to this project will also be released into the public domain. See our CONTRIBUTING file for more details.