Hack Oregon Jobs Economy Backend

This is the backend REST API for Hack Oregon's Job's Economy team. It consists of a Flask application, as well as Vagrant and Docker scripts.

To run locally without Vagrant and Docker:

cd backend

virtualenv -p python3 env

source env/bin/activate

pip install -r setup/requirements.txt

pip install -r setup/dev-requirements.txt

python jobs-economy/run.py

Visit 0.0.0.0:5000 in your browser.

To run on server without Vagrant and Docker:

sudo apt-get install python3-pip

cd backend

virtualenv -p python3 env

source env/bin/activate

pip install -r setup/requirements.txt

pip install -r setup/server-requirements.txt

sudo env/bin/gunicorn -b 0.0.0.0:80 jobs-economy/app:app

To run with Vagrant and the Docker provisioner:

You must have Vagrant installed, along with Virtualbox.

Vagrant up

Wait for Vagrant and Docker to complete their magic, then visit 0.0.0.0:8080 in your browser.

API Documentation

This API exposes the data used for Hack Oregon's Raise Effect project. It is a read-only RESTful API that uses JSON for its interchange format. Data is organized by county and family type.

The base URL is: /api/v1/counties

Data sets

• Populations: /populations
• Labor Statistics: /laborstats
• Wage Statistics: /wagestats
• Self-Sufficiency Standard Budgets: /sssbudgets
• Self-Sufficiency Standard Tax Credits: /ssscredits
• Self-Sufficiency Standard Wages: /ssswages
• PUMA Codes: /pumas
• Census Households /censushouseholds
• Family Code Weights /familycodeweights
• Additional Calculated Statistics (see API reference): /calculatedstats

Example requests

Sending a GET request to the root of the resource will download the data for all counties. The JSON data returned is an object with one key called "data", which contains an array of county data objects:

    GET /api/v1/counties

    HTTP/1.1 200 OK
    {
      "data": [
        {
          "fips": 41001,
          "name": "Baker"
        },
        ...
      ]
    }

Retrieve a particular data set by appending the corresponding URL:

    GET /api/v1/counties/laborstats

    HTTP/1.1 200 OK
    {
      "data": [
        {
        "employed": 6024.0,
          "fips": 41001,
          "laborForce": 6615.0,
          "unemployed": 591.0,
          "unemploymentRate": 8.9,
          "urSeasonalAdj": 7.3,
          "year": 2014
        },
        {
          "employed": 42507.0,
          "fips": 41003,
          "laborForce": 44777.0,
          "unemployed": 2270.0,
          "unemploymentRate": 5.1,
          "urSeasonalAdj": 5.1,
          "year": 2014
        },
        ...
        ]
    }

Retrieve data for a particular county by including the county's FIPS code before the data set. In this case, the "data" key contains a single object. The example below returns data for Clackamas county:

    GET /api/v1/counties/41005/populations

    HTTP/1.1 200 OK

    {
      "data": {
        "a1c0": 23581.0,
        "a1c": 7742.0,
        "a1teen": 0.0,
        "a2s2": 2266.0,
        "adults": 1.912958,
        "fips": 41005,
        "kids": 0.871108,
        "kidsPresent": 46179.0,
        "minDiff": 1333.151101,
        "mostCommonFamilyType": "a3i0p0s0t0",
        "population": 386080.0,
        "year": 2013
      }
    }

API reference

Data set fields

Counties

• fips:integer fips code, primary key
• county:string county name

Family Type

• familyCode:string - SSS family code, primary key
• descriptionFc:string - description of the people in the household
• familyCodeRollup:string - simplified family code that sums children regardless of age
• descriptionFcr:string - description of the people in the household
• adult:string - number of adults
• infant:integer - number of infants
• preschooler:integer - number of preschoolers
• schoolAge:integer - number of school-age children
• teenager:integer - number of teenagers
• children:integer - total number of children

Population

• fips:integer - foreign key, references counties(fips)
• population:float - estimated population as of July 1, 2014
• adults:float - average number of adults in household by county
• kids:float - average number of kids in household by county
• kidsPresent:float - total households with kids in county
• a1c:float - total households with one adult and any children in county
• a2s2:float - total households with two adults and two school-age children in county
• a1c0:float - total households with one adult and no children in county
• a1teen:float - total households with a single adult under the age of 20 in county
• kidsPresentPer:float - percent of households in county with children
• a1cPer:float - percent of households in county with a single adult and children
• a2s2Per:float - percent of households in county with two adults and two school-age children
• a1c0Per:float - percent of households in county with a single adult and no children
• a1teenPer:float - percent of households in county with a single adult under age 20
• minDiff:float - absolute value of difference between famcode annual Standard and county average Standard
• mostCommonFamilyType:float - family type with SSS that comes closest to county average SSS, foreign key, references familytype(familycode)
• year:integer - year represented by data

Labor Statistics

• fips:integer - foreign key, references counties(fips)
• laborForce:float - civilian labor force
• employed:float - employed
• unemployed:float - unemployed
• unemploymentRate:float - unemployment rate (UR)
• urSeasonalAdj:float - seasonally adjusted UR
• year:integer - year represented by data

Wage Statistics

• fips:integer - foreign key, references counties(fips) -householdMedianIncome:integer - _ _ -familyMedianIncome:integer - _ _ -marriedMedianIncome:integer - _ _ -nonFamilyMedianIncome:integer - _ _
• lessThan10Hour:float - Jobs paying less than $10/hr
• btwn10And15Hour:float - Jobs paying $10-$14.99
• totalUnder15:float - Total Under $15/Hour
• percentHouseholdsBreak1 - _ _ ...
• percentHouseholdsBreak10 - _ _
• year:integer - year represented by data

Calculated Statistics

• fips:integer - foreign key, references counties(fips)
• percentORKids:float - Percentage of State's kids
• a1AllPer:float - percentage Single Adults with and without children
• a2AllPer:float - percentage Couples
• c0AllPer:float - percentage households with no children

Self-Sufficiency Standard Budget

• familycode:string - foreign key, references familytype(familycode)
• housing:float - monthly cost of housing
• childcare:float - monthly cost of childcare
• food:float - monthly cost of food
• transportation:float - monthly cost of transportation
• healthcare:float - monthly cost of healthcare
• miscellaneous:float - monthly miscellaneous costs
• taxes:float - monthly taxes owed
• fips:integer - foreign key, references counties(fips)
• year:integer - year represented by data

Self-Sufficiency Standard Tax Credits

• familycode:string - foreign key, references familytype(familycode)
• oregonWorkingFamilyCredit:float - amount that can be deducted monthly for oregon working family childcare tax credit (stored as negative value)
• earnedIncomeTax:float - amount that can be deducted monthly for earned income tax credit (stored as negative value)
• childcareTax:float - amount that can be deducted monthly for childcare tax credit (stored as negative value)
• childTax:float - amount that can be deducted monthly for child tax credit (stored as negative value)
• fips:integer - foreign key, references counties(fips)
• year:integer -year represented by data

Self-Sufficiency Standard Wages

• familyCode:string - foreign key, references familytype(familycode)
• hourly:float - hourly self sufficiency standard wage
• qualifier:text - describes whether wage applies to individuals or couples
• monthly:float - monthly self sufficiency standard wage
• annual:float - annual self sufficiency standard wage
• fips:integer - foreign key, references counties(fips)
• year:integer - year represented by data

PUMA codes

• fips:integer - foreign key, references counties(fips)
• pumaCode:integer - puma code
• areaName:text - short name of puma area
• pumaName:text - long name of puma area
• pumaPopulation:float - population of puma area
• pumaWeight:float - weight of puma area

Census Household

• fips:integer - foreign key, references counties(fips)
• totalHouseholds:integer - number of households in county
• totalMarriedFamilyHouseholds:integer - _ _
• totalNonFamilyHouseholds:integer - _ _
• totalUnmarriedFamilyHouseholds:integer - _ _
• lowIncomeSingleParents:integer - number of low income single parents in county
• lowIncomeMarriedParents:integer - number of low income married parents in county
• lowIncomeSingleAdults:integer - number of low income single adults in county
• marriedAsPercentTotal:float - _ _
• lowIncomeMarriedParentsAsPercentTotal:float - _ _
• lowIncomeMarriedParentsAsPercentMarried:float - _ _
• unmarriedAsPercentTotal:float - _ _
• lowIncomeSingleParentsAsPercentTotal:float - _ _
• lowIncomeSingleParentsAsPercentUnmarried:float - _ _
• nonFamilyAsPercentTotal:float - _ _
• lowIncomeSingleAdultsAsPercentTotal:float - _ _
• lowIncomeSingleAdultsAsPercentNonFamily:float - _ _

Family Code Weights

• fips:integer foreign key, references counties(fips)
• familyCode:string foreign key, references familytype(familycode)
• weight:float portion of county population that matches family type, where total county population is 1