Use Case 49: API for Federal Poverty Guidelines

From Demand-Driven Open Data for HHS
Jump to: navigation, search


Use case summary


  • Federal poverty guidelines are used to determine eligibility for a number of federal, state, and local social support benefits.

e.g. a benefit eligibility calculation might look something like:

if { [head-of-household-income] < 185% * FPL-for-[N-family-size] } 
{eligible for .2 * FPL-for-[N-family-size] }
Return benefit amount.

and would translate in numbers to:

if { $2000/mo < 185% * $1647 } 
{eligible for .2 * 1647}
Benefit amount: $329.4

Developers of these types of algorithms have to maintain a calculation that updates twice per year. Ideally, this is the sort of data that could be queried dynamically via an API and returned to webapps that use the federal poverty guidelines as a means test for these or other benefits or systems.


  • Value to customer: Returning the federal poverty guideline data via an API would reduce the burden associated with maintaining an algorithm that determines benefit eligibility.
  • Value to industry/public: Calculating eligibility is a challenge in a number of contexts for providing social services, from service referral to benefits enrollment to affordable housing etc -- and income is one of the harder components of eligibility. This would be a small but significant piece of a hugely important puzzle.


Current data and limitation


  • Fields:
Field Type Request / Response Note
household_size Integer Request Household size, per per definition
household_income Currency Request FPL household income
income_type Monthly/Annual Request Default to annual
year YYYY Request Applicable year for calculation
state_code 2-letter code Request Optional state, outside continental U.S.
fpl_amount Dollars Response 100% FPL based for size and year
fpl_percentage Percent Response income as percent of fpl_amount
year_base Integer Response Used to calc fpl_amount, dep. on year
year_rate Integer Response Used to calc fpl_amount, dep. on year

  • Update frequency: Defined annually
  • Joins between datasets: state_code, year
  • History: Definitions for all prior years
  • Delivery mechanism: API with JSON response


Long term implementation

An API has been implemented by a Code for America team[1] in May 2015

  • Query parameters: (See Specifications section)
    • size -- Household size
    • income -- Household income
    • income_type -- Monthly or annual
    • year -- if not specified, defaults to current year
    • (state_code is not implemented at this time, but is applicable only to Alaska and Hawaii)

  1. Developed by @mapsam, @apranav19, @daguar