The Poverty Calculator has an application programming interface located at: http://uspovertydata.com/povcal/api.php.
How It Works (Quick Guide)
The API takes a simple GET method and returns JSON. The easiest way to see how it works is to perform a specific calculation on the normal poverty calculator and then change the resulting URL from “index.php” to “api.php.”
For example. Here is the URL that shows up if you use the poverty calculator interface to select the 2010 Supplemental Poverty Metric calculation:
If you change this URL from “index.php” to “api.php”, it looks like this:
If you click on that link, you’ll see this:
{"povamount":50.595,"povrate":16.5,"whitepovamount":22.204,"whitepovrate":11.4,"whitepovshare":43.9,"whitechildpovamount":4.146,"whitechildpovrate":10.5,"whitechildpovshare":8.2,"whiteadultpovamount":13.81,"whiteadultpovrate":11.2,"whiteadultpovshare":27.3,"whiteelderlypovamount":4.248,"whiteelderlypovrate":13.4,"whiteelderlypovshare":8.4,"hispanicpovamount":14.756,"hispanicpovrate":28.9,"hispanicpovshare":29.2,"hispanicchildpovamount":5.482,"hispanicchildpovrate":31.4,"hispanicchildpovshare":10.8,"hispanicadultpovamount":8.479,"hispanicadultpovrate":27.6,"hispanicadultpovshare":16.8,"hispanicelderlypovamount":0.795,"hispanicelderlypovrate":27.8,"hispanicelderlypovshare":1.6,"blackpovamount":9.421,"blackpovrate":25.6,"blackpovshare":18.6,"blackchildpovamount":3.008,"blackchildpovrate":29.2,"blackchildpovshare":5.9,"blackadultpovamount":5.577,"blackadultpovrate":24.1,"blackadultpovshare":11,"blackelderlypovamount":0.836,"blackelderlypovrate":25.1,"blackelderlypovshare":1.7,"asianpovamount":2.531,"asianpovrate":16.7,"asianpovshare":5,"multipovamount":0.987,"multipovrate":17.7,"multipovshare":2,"nativepovamount":0.485,"nativepovrate":23.2,"nativepovshare":1,"pipovamount":0.211,"pipovrate":23.8,"pipovshare":0.4,"malepovamount":23.692,"malepovrate":15.8,"malepovshare":46.8,"femalepovamount":26.902,"femalepovrate":17.2,"femalepovshare":53.2,"age0povamount":13.832,"age0povrate":18.6,"age0povshare":27.3,"ageadultpovamount":30.404,"ageadultpovrate":15.8,"ageadultpovshare":60.1,"age1povamount":5.147,"age1povrate":21.1,"age1povshare":10.2,"age2povamount":8.685,"age2povrate":17.4,"age2povshare":17.2,"age3povamount":7.433,"age3povrate":24.9,"age3povshare":14.7,"age4povamount":6.514,"age4povrate":16,"age4povshare":12.9,"age5povamount":5.48,"age5povrate":13.6,"age5povshare":10.8,"age6povamount":6.08,"age6povrate":13.8,"age6povshare":12,"age7povamount":4.898,"age7povrate":13,"age7povshare":9.7,"age8povamount":6.359,"age8povrate":16,"age8povshare":12.6,"disabledpovamount":6.687,"disabledpovrate":24.1,"disabledpovshare":13.2,"disabledadultpovamount":4.182,"disabledadultpovrate":27.9,"disabledadultpovshare":8.3,"marketincomeform":"1","ssform":"1","ssiform":"1","ucform":"1","welfareform":"1","veteransform":"1","snapform":"1","schoollunchform":"1","wicform":"1","housingform":"1","energyform":"1","eitcform":"1","ctcform":"1","incometaxform":"1","payrolltaxform":"1","statetaxform":"1","childsupportpaidform":"1","moopform":"1","childandworkform":"1","povlineform":"spm100","yearform":"2010"}
That is the JSON output. You can compare the numbers in the API output to those that show up in the poverty calculator interface for the same query to get a sense of what each key refers to.
Note: The “&action=Recalculate” part of the URL is unnecessary for direct API calls.
How It Works (Long Guide)
I recommend using the Quick Guide first to see if you can figure it out. If not, then look to this guide for a more thorough account.
A. General Functioning
The API takes a GET method and returns JSON. This means that all calls to the API will start with “http://uspovertydata.com/povcal/api.php?” and then include a string of variables that take the form of:
&variable1=value1&variable2=value2
In this string, “variable” refers to the name of the specific variable being passed and “value” refers to what that variable is set to.
For example, if you want to receive the poverty calculation for market income only using the supplemental poverty line for 2012, the variables and values are:
- marketincome=1
- povline=spm100
- year=2012
Accordingly, the call to the API will be:
http://uspovertydata.com/povcal/api.php?marketincome=1&povline=spm100&year=2012
The API takes the input variables that are provided though the GET method described above and returns a JSON output with a long list of output variables that can be used by programmers for their own applications. For the API call above, the list of output variables can be seen by clicking on that link or here:
{"povamount":74.717,"povrate":24,"whitepovamount":37.529,"whitepovrate":19.2,"whitepovshare":50.2,"whitechildpovamount":5.152,"whitechildpovrate":13.2,"whitechildpovshare":6.9,"whiteadultpovamount":16.741,"whiteadultpovrate":13.7,"whiteadultpovshare":22.4,"whiteelderlypovamount":15.635,"whiteelderlypovrate":45.8,"whiteelderlypovshare":20.9,"hispanicpovamount":17.904,"hispanicpovrate":33.6,"hispanicpovshare":24,"hispanicchildpovamount":6.805,"hispanicchildpovrate":38.3,"hispanicchildpovshare":9.1,"hispanicadultpovamount":9.238,"hispanicadultpovrate":28.7,"hispanicadultpovshare":12.4,"hispanicelderlypovamount":1.861,"hispanicelderlypovrate":57.9,"hispanicelderlypovshare":2.5,"blackpovamount":13.868,"blackpovrate":36.9,"blackpovshare":18.6,"blackchildpovamount":4.346,"blackchildpovrate":42.6,"blackchildpovshare":5.8,"blackadultpovamount":7.432,"blackadultpovrate":31.4,"blackadultpovshare":9.9,"blackelderlypovamount":2.089,"blackelderlypovrate":55.7,"blackelderlypovshare":2.8,"asianpovamount":2.882,"asianpovrate":18.1,"asianpovshare":3.9,"multipovamount":1.444,"multipovrate":24.7,"multipovshare":1.9,"nativepovamount":0.9,"nativepovrate":39.7,"nativepovshare":1.2,"pipovamount":0.191,"pipovrate":20.6,"pipovshare":0.3,"malepovamount":33.72,"malepovrate":22.1,"malepovshare":45.1,"femalepovamount":40.997,"femalepovrate":25.8,"femalepovshare":54.9,"age0povamount":17.996,"age0povrate":24.3,"age0povshare":24.1,"ageadultpovamount":36.212,"ageadultpovrate":18.7,"ageadultpovshare":48.5,"age1povamount":6.334,"age1povrate":26.3,"age1povshare":8.5,"age2povamount":11.663,"age2povrate":23.3,"age2povshare":15.6,"age3povamount":7.159,"age3povrate":23.8,"age3povshare":9.6,"age4povamount":7.644,"age4povrate":18.3,"age4povshare":10.2,"age5povamount":6.528,"age5povrate":16.4,"age5povshare":8.7,"age6povamount":7.031,"age6povrate":16.2,"age6povshare":9.4,"age7povamount":7.85,"age7povrate":20.4,"age7povshare":10.5,"age8povamount":20.509,"age8povrate":47.4,"age8povshare":27.4,"disabledpovamount":15.049,"disabledpovrate":52.1,"disabledpovshare":20.1,"disabledadultpovamount":7.053,"disabledadultpovrate":47,"disabledadultpovshare":9.4,"marketincomeform":"1","ssform":"","ssiform":"","ucform":"","welfareform":"","veteransform":"","snapform":"","schoollunchform":"","wicform":"","housingform":"","energyform":"","eitcform":"","ctcform":"","incometaxform":"","payrolltaxform":"","statetaxform":"","childsupportpaidform":"","moopform":"","childandworkform":"","povlineform":"spm100","yearform":"2012"}
B. Input Variables
In this section, I provide a comprehensive list of the possible input variables that can be passed to the API via GET and their possible values.
For the following variables, the only possible values are ’1′ and other. If the value is set to ’1′, then the relevant income or income reduction will be included in the poverty calculation. If the value is set to anything other than ’1′, or not set at all, then the income or income reduction will not be included in the poverty calculation.
- marketincome – Market Income
- ss – Social Security
- ssi – Supplemental Security Income
- uc – Unemployment Compensation
- welfare – Welfare (TANF)
- veterans – Veteran’s Benefits
- snap – Food Stamps ( TANF)
- schoollunch – Free/Subsidized School Lunch
- wic – Women, Infants, & Children (WIC)
- housing – Housing Subsidies (e.g. Section 8)
- energy – Energy Subsidies (e.g. LIHEAP)
- eitc – Earned Income Tax Credit
- ctc – Child Tax Credit
- incometax – Federal Income Tax
- payrolltax – Federal Payroll Tax
- statetax – State Taxes
- childsupportpaid – Child Support Paid
- moop – Medical Out-of-Pocket Expenditures
- childandwork – Child Care & Work-Related Expenses
The other input variables allow for multiple values. They are detailed below.
- povline – Poverty Line/Unit. This variable takes six possible values:
- spm100 – Supplemental Poverty Line
- spm50 – Supplemental Deep Poverty Line (50% of Supplemental Poverty Line)
- spm150 – Supplemental Near Poverty Line (150% of Supplemental Poverty Line)
- opm100 – Official Poverty Line
- opm50 – Official Deep Poverty Line (50% of Official Poverty Line)
- opm150 – Supplemental Near Poverty Line (150% of Official Poverty Line)
- year – Year. This variable takes four possible values:
- 2012
- 2011
- 2010
- 2009
These are all of the input variables. They can be mixed and matched in all sorts of ways to generate different poverty calculations. How to send these variables with their desired values to the API is explained in Section A above.
C. Output Variables
After you’ve made a GET request, you will receive a JSON output with many output variables. That output will take the form of:
{"variable1":value1,"variable2":"value2"}
In this output, “variable” refers to the name of the specific output variable and “value” refers to the value of that specific output variable.
The initial output variables match up exactly with the “Poverty Calculation” part of the poverty calculator interface. It is probably most helpful to just look through that to see what each variable means.
There are far too many output variables to make it worth listing them here. However, the variables are consistently named in a way that makes it possible to explain each name’s constituent parts. By adding those constituent parts together, you’ll be able to understand every particular variable.
Poverty
- pov – All variables with this term refer to poverty.
Amount/Rate/Share
- amount – This variable refers to the raw number of people who are impoverished in the given category. The value is provided in millions. For example, if whitepovamount says 21.351, that means 21.351 million white people are in poverty.
- rate – This variable refers to the percentage of people who are impoverished in a given category. This value is provided in percents. For example, if whitepovrate says 13.2, that means 13.2% of white people are in poverty.
- share – This variable refers to share of all impoverished people who fall into a given category. This value is provided in percents. For example, if whitepovshare says 42.4, that means 42.4% of all impoverished people are white people. For another example, if blackadultpovshare says 8.7, that means 8.7% of all impoverished people are black adults.
Race
- white – Non-Hispanic Whites.
- hispanic – Hispanics.
- black – Non-Hispanic Blacks.
- asian – Non-Hispanic Asians.
- multi – Non-Hispanics who have multiple races.
- native – Non-Hispanic Natives, i.e. indigenous people.
- pi – Non-Hispanic Pacific Islanders.
Sex
- male – Males.
- female – Females.
Age
- child – Aged 0-17.
- adult – Aged 18-64.
- elderly – Aged 65+.
- age1 – Aged 0 – 5.
- age2 – Aged 6 – 17.
- age3 – Aged 18 – 24.
- age4 – Aged 25 – 34.
- age5 – Aged 35 – 44.
- age6 – Aged 45 – 54.
- age7 – Aged 55 – 64.
- age8 – Aged 65+.
You’ll notice, “age8″ and “elderly” are the same.
Disabled
- disabled – Has a serious disability.
Forms
The very last set of variables in the JSON all end in the word “form.” These variables are helpful because they tell you exactly what the poverty calculator did in this execution. As explained in Section D below, sometimes the poverty calculator does something other than what you might expect if you provided input that was not proper. In an application, these variables can be used to communicate to the application user what exactly they are seeing. For example, I use these variables to determine what boxes to check in the poverty calculator interface after someone has hit “Recalculate” and the page is reloaded with the new calculation.
The prefix to these variables exactly match the input variables in Section B above. So, for instance, ssform is the “form” variable for Social Security. If it is set to ’1′, then that means Social Security was included in the poverty calculation. If it is set to “” (empty), then it was not. The same goes for every other “form” variable. Match the prefix to the variables in Section B to know what the variable refers to.
D. Quirks and Oddities
Here is a list of one-off bits worth noting about certain strange ways the API works:
- Default Calculation – If you do not provide any parameters at all, i.e. you just call http://uspovertydata.com/povcal/api.php, the API returns values equal to a default poverty metric. Right now, that default poverty metric is the 2012 Supplemental Poverty Measure.
- Default Lines/Years – If you fail to provide a povline variable or a year variable, the API fills those variables in with default values. Right now, those default values are “spm100″ and “2012″ respectively.
- Official Poverty Metric – The Official Poverty Metric only considers incomes from marketincome, ss, ssi, uc, welfare, veterans. If you include any other incomes or income reducers in an API call that uses one of the Official Poverty Lines for povline (i.e. povline is set to opm100, opm50, or opm150), they will be ignored.