Using the API

You can query the database by sending an HTTP request with GET variables to one of the following methods. Click a method to jump to its documentation.

  1. getBudgetAccount — Returns account level details.
  2. getBudgetAggregate — Returns cumulative totals by agency, bureau, function or subfunction.
  3. getReceiptAccount — Returns account level receipt details.
  4. getReceiptAggregate — Returns cumulative receipt totals by agency, bureau, category or subcategory.
  5. getPopulation — Returns the national population for each year.
  6. getGDP — Returns national GDP for each year.
  7. getDebt — Returns the cumulative national debt during a given year.
  8. getTaxRates — Returns social security, and Medicare, and federal income tax rate brackets.
  9. getInflation — Returns the average price index of consumer goods (inflation).

In return, the API replies with XML. Each of these methods can handle a variety of parameters to filter the data. Read below to learn how to use these methods.

We've also included a basic HTML / JavaScript template that allows you to easily poll the WhatWePayFor API.
Click here to view an example template.

getBudgetAccountBack to Top

Description

This method retrieves account level details. An account is the smallest "bucket" that tax money can full under. The following illustrates the hierarchy of payment categories:

Agency
Department of Labor
Bureau
Employment and Training Administration
Function
Income Security (Broadest)
Sub-Function
Unemployment Compensation
Account
Unemployment Trust Fund (Most granular)

Example Calls

Parameters

year
Year in YYYY
2010
income
Taxable income in dollars per year
0 (nationwide totals)
exacttax
The exact amount paid in taxes.
none (overrides the income & filing parameters if specified)
function
Integer ID for function
0 (all functions)
subfunction
Integer ID for subfunction
0 (all subfunctions)
agency
Integer ID for agency
0 (all agencies)
bureau
Integer ID for bureau
0 (all bureaus)
account
Integer ID for account
0 (all accounts)
adjustInflationYear
Year in YYYY
none (based on year parameter)
type
  • 0 All
  • 1 Mandatory
  • 2 Discretionary
  • 3 Net Interest
0 (all)
sortby
  • 0 Total
  • 1 Change (Value)
  • 2 Change (Percentage)
  • 3 Name
0 (total)
sortdir
  • 0 Descending
  • 1 Ascending
0 (descending)
filing
  • 0 Single
  • 1 Married Filing Jointly
  • 2 Married Filing Separately
  • 3 Head of Household
0 (single)
selfEmployed
  • 0 Not Self-Employed
  • 1 Self-Employed
0
showExtra
  • 0Omits attributes perCapitaI & gdpP
  • 1Includes attributes perCapitaI & gdpP
0
showChange
  • 0Omits attributes changei & changep
  • 1Includes attributes changei & changep
0

Example Response

Here's an example of the type of response you can expect from a call to getBudgetAccount.

http://www.whatwepayfor.com/api/getBudgetAccount?income=50000&showChange=1&showExtra=1

<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
  <item account="Federal Old-age and Survivors Insurance Trust Fund" agency="Misc Agencies" bureau="Social Security Administration" function="Social Security" subfunction="Social security" spendingType="1" onBudget="true" accountID="4823" agencyID="6950" bureauID="4822" functionID="2784" subfunctionID="2839" amounti="579937000" mycosti="2018.38" changei="26610000" changep="0.0481" />
  <item account="Grants to States for Medicaid" agency="Department of Health and Human Services" bureau="Centers for Medicare and Medicaid Services" function="Health" subfunction="Health care services" spendingType="1" onBudget="false" accountID="3904" agencyID="3815" bureauID="3902" functionID="2781" subfunctionID="2829" amounti="292677000" mycosti="1018.62" changei="37787000" changep="0.1482" />
  <item account="Federal Hospital Insurance Trust Fund" agency="Department of Health and Human Services" bureau="Centers for Medicare and Medicaid Services" function="Medicare" subfunction="Medicare" spendingType="1" onBudget="false" accountID="3912" agencyID="3815" bureauID="3902" functionID="2782" subfunctionID="2832" amounti="249394000" mycosti="867.98" changei="7558000" changep="0.0313" />
  <item account="Payments to Health Care Trust Funds" agency="Department of Health and Human Services" bureau="Centers for Medicare and Medicaid Services" function="Medicare" subfunction="Medicare" spendingType="1" onBudget="false" accountID="3908" agencyID="3815" bureauID="3902" functionID="2782" subfunctionID="2832" amounti="229903000" mycosti="800.14" changei="16880000" changep="0.0792" />
  <item account="Interest on Treasury Debt Securities (gross)" agency="Department of the Treasury" bureau="Interest on the Public Debt" function="Net Interest" subfunction="Interest on Treasury debt securities (gross)" spendingType="3" onBudget="false" accountID="4798" agencyID="4549" bureauID="4795" functionID="2788" subfunctionID="2857" amounti="220955000" mycosti="769.00" changei="31565000" changep="0.1667" />
  <item account="Federal Supplementary Medical Insurance Trust Fund" agency="Department of Health and Human Services" bureau="Centers for Medicare and Medicaid Services" function="Medicare" subfunction="Medicare" spendingType="1" onBudget="false" accountID="3911" agencyID="3815" bureauID="3902" functionID="2782" subfunctionID="2832" amounti="220623000" mycosti="767.84" changei="15412000" changep="0.0751" />
  <item account="Interest Paid to Trust Fund Receipt Accounts - Shadow Account" agency="Department of the Treasury" bureau="Interest on the Public Debt" function="Net Interest" subfunction="Interest on Treasury debt securities (gross)" spendingType="3" onBudget="false" accountID="4799" agencyID="4549" bureauID="4795" functionID="2788" subfunctionID="2857" amounti="190815000" mycosti="664.10" changei="9935000" changep="0.0549" />
  <item account="Unemployment Trust Fund" agency="Department of Labor" bureau="Employment and Training Administration" function="Income Security" subfunction="Unemployment compensation" spendingType="1" onBudget="false" accountID="4420" agencyID="4379" bureauID="4404" functionID="2783" subfunctionID="2835" amounti="180067000" mycosti="626.70" changei="63234000" changep="0.5412" />
  <item account="Federal Disability Insurance Trust Fund" agency="Misc Agencies" bureau="Social Security Administration" function="Social Security" subfunction="Social security" spendingType="1" onBudget="true" accountID="4834" agencyID="6950" bureauID="4822" functionID="2784" subfunctionID="2839" amounti="124998000" mycosti="435.04" changei="7910000" changep="0.0676" />
  <item account="Operation and Maintenance, Army" agency="Department of Defense--Military" bureau="Operation and Maintenance" function="National Defense" subfunction="Department of Defense-Military" spendingType="2" onBudget="false" accountID="3684" agencyID="3541" bureauID="3644" functionID="2771" subfunctionID="2791" amounti="90135000" mycosti="313.70" changei="6517000" changep="0.0779" />
  <item account="Payments to the Unemployment Trust Fund" agency="Department of Labor" bureau="Employment and Training Administration" function="Income Security" subfunction="Unemployment compensation" spendingType="1" onBudget="false" accountID="4411" agencyID="4379" bureauID="4404" functionID="2783" subfunctionID="2835" amounti="75255000" mycosti="261.91" changei="58037000" changep="3.3707" />
  <item account="Civil Service Retirement and Disability Fund" agency="Misc Agencies" bureau="Office of Personnel Management" function="Income Security" subfunction="Federal employee retirement and disability" spendingType="1" onBudget="false" accountID="5608" agencyID="6950" bureauID="5596" functionID="2783" subfunctionID="2834" amounti="70238000" mycosti="244.45" changei="2278000" changep="0.0335" />
  <item account="Supplemental Nutrition Assistance Program" agency="Department of Agriculture" bureau="Food and Nutrition Service" function="Income Security" subfunction="Food and nutrition assistance" spendingType="1" onBudget="false" accountID="3395" agencyID="3117" bureauID="3393" functionID="2783" subfunctionID="2837" amounti="68692000" mycosti="239.07" changei="9566000" changep="0.1618" />
  <item account="Medicare Prescription Drug Account, Federal Supplementary Insurance Trust Fund" agency="Department of Health and Human Services" bureau="Centers for Medicare and Medicaid Services" function="Medicare" subfunction="Medicare" spendingType="1" onBudget="false" accountID="3915" agencyID="3815" bureauID="3902" functionID="2782" subfunctionID="2832" amounti="58784000" mycosti="204.59" changei="5625000" changep="0.1058" />
  <item account="Payment to Military Retirement Fund" agency="Other Defense Civil Programs" bureau="Military Retirement" function="National Defense" subfunction="Defense-related activities" spendingType="1" onBudget="false" accountID="5926" agencyID="5921" bureauID="5924" functionID="2771" subfunctionID="2793" amounti="58619000" mycosti="204.01" changei="7494000" changep="0.1466" />

Keep in mind that unfiltered calls to getBudgetAccount will return lots of items (this call in particular returns just under 2,000 items). In the example above, the majority of the response is omitted.

Each <item> tag represents an account, and its attributes describe that account. You can find the name and integer ID's for the account as well as those for the bureau, agency, sub-function and function that it belongs to.

Most important are the attributes describing dollar amounts, which are broken down as follows:

amounti
Total budget for this account nationally, in dollars.
changei
Change in total budget for this account nationally from previous year, in dollars.
Only appears if showChange is set to 1.
changep
Change in total budget for this account nationally from previous year, in percent.
Only appears if showChange is set to 1.
mycosti
Amount paid for this account by an individual with specified income.
If you omit the income parameter, this attribute will be omitted.
perCapitaI
Total amount per capita.
Only appears if showExtra is set to 1.
gdpP
Percentage of the total amount compared to GDP (Gross Domestic Product).
Only appears if showExtra is set to 1.

getBudgetAggregateBack to Top

Description

getBudgetAggregate is used for obtaining sums. getBudgetAggregate works like getBudgetAccount, but returns cumulative totals by agency, bureau, function or subfunction.

Example Calls

Parameters

getBudgetAggregate accepts the same parameters as getBudgetAccount with one addition.

group
  • function
  • subfunction
  • agency
  • bureau
function

Keep in mind that grouping by a dimension that does not exist in your response will result in an empty response. For example, you can't request a specific function with the function parameter and then group by Bureau.

Example Response

http://www.whatwepayfor.com/api/getBudgetAggregate?group=function

<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
  <item dimensionID="2784" dimensionName="Social Security" spendingpe="0" amounti="723504000" changei="33703000" changep="0.0489" mycosti="0.00" />
  <item dimensionID="2771" dimensionName="National Defense" spendingpe="0" amounti="722138000" changei="24375000" changep="0.0349" mycosti="0.00" />
  <item dimensionID="2783" dimensionName="Income Security" spendingpe="0" amounti="664559000" changei="53988000" changep="0.0884" mycosti="0.00" />
  <item dimensionID="2782" dimensionName="Medicare" spendingpe="0" amounti="462087000" changei="25100000" changep="0.0574" mycosti="0.00" />
  <item dimensionID="2781" dimensionName="Health" spendingpe="0" amounti="386437000" changei="12821000" changep="0.0343" mycosti="0.00" />
  <item dimensionID="2788" dimensionName="Net Interest" spendingpe="0" amounti="187775000" changei="871000" changep="0.0047" mycosti="0.00" />
  <item dimensionID="2785" dimensionName="Veterans Benefits and Services" spendingpe="0" amounti="125002000" changei="28054000" changep="0.2894" mycosti="0.00" />
  <item dimensionID="2778" dimensionName="Transportation" spendingpe="0" amounti="93669000" changei="-31326000" changep="-0.2506" mycosti="0.00" />
  <item dimensionID="2780" dimensionName="Education, Training, Employment, and Social Services" spendingpe="0" amounti="91920000" changei="-75635000" changep="-0.4514" mycosti="0.00" />
  <item dimensionID="2772" dimensionName="International Affairs" spendingpe="0" amounti="67388000" changei="4012000" changep="0.0633" mycosti="0.00" />
  <item dimensionID="2789" dimensionName="Allowances" spendingpe="0" amounti="60500000" changei="60500000" changep="0.0000" mycosti="0.00" />
  <item dimensionID="2786" dimensionName="Administration of Justice" spendingpe="0" amounti="53462000" changei="-3141000" changep="-0.0555" mycosti="0.00" />
  <item dimensionID="2775" dimensionName="Natural Resources and Environment" spendingpe="0" amounti="39520000" changei="-17873000" changep="-0.3114" mycosti="0.00" />
  <item dimensionID="2773" dimensionName="General Science, Space, and Technology" spendingpe="0" amounti="31023000" changei="-4013000" changep="-0.1145" mycosti="0.00" />
  <item dimensionID="2787" dimensionName="General Government" spendingpe="0" amounti="29010000" changei="-1210000" changep="-0.0400" mycosti="0.00" />
  <item dimensionID="2776" dimensionName="Agriculture" spendingpe="0" amounti="25419000" changei="1283000" changep="0.0532" mycosti="0.00" />
  <item dimensionID="2779" dimensionName="Community and Regional Development" spendingpe="0" amounti="19884000" changei="-3875000" changep="-0.1631" mycosti="0.00" />
  <item dimensionID="2774" dimensionName="Energy" spendingpe="0" amounti="8810000" changei="-33989000" changep="-0.7942" mycosti="0.00" />
  <item dimensionID="2790" dimensionName="Undistributed Offsetting Receipts" spendingpe="0" amounti="-79731000" changei="12908000" changep="-0.1393" mycosti="0.00" />
  <item dimensionID="2777" dimensionName="Commerce and Housing Credit" spendingpe="0" amounti="-111799000" changei="-563468000" changep="-1.2475" mycosti="0.00" />
</response>

In this case, we're getting a single <item> per function. The values in attributes like amounti or changei represent the sum total of values for accounts belonging to the function in question.

getReceiptAccountBack to Top

Description

Retrieves account level details for "receipts." Where as the getBudgetXXX methods provide information describing what a taxpayer contributes, the getReceiptXXX methods provide information about what the government receives.

The hierarchy of receipt categories are as follows. Note that the name "category" replaces "function."

Agency
Department of Transportation
Bureau
Department of Transportation
Category
Excise Taxes (Broadest)
Sub-Category
Trust Fund Excise Taxes
Account
Highway Trust Fund, Deposits (Mass Transit Account)(Most granular)

Example Calls

Parameters

getReceiptAccount accepts the same parameters as getBudgetAccount with some small differences.

function category
Integer ID for category
0 (all categories)
subfunction subcategory
Integer ID for subcategory
0 (all subcategories)
income
Not supported by this method.

Example Response

http://www.whatwepayfor.com/api/getReceiptAccount?year=2005&category=931&showChange=1

<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
  <item account="Individual Income Taxes" agency="Governmental Receipts" bureau="Governmental Receipts" category="Individual Income Taxes" subcategory="Individual Income Taxes" accoutID="11050" agencyID="901" bureauID="0" categoryID="931" subcategoryID="0" year="2005" amounti="927169000.00" changei="118266000.00" changep="0.146205" />
  <item account="Presidential Election Campaign Fund" agency="Governmental Receipts" bureau="Governmental Receipts" category="Individual Income Taxes" subcategory="Individual Income Taxes" accoutID="508110" agencyID="901" bureauID="0" categoryID="931" subcategoryID="0" year="2005" amounti="53000.00" changei="-3000.00" changep="-0.053571" />
</response>

The response above represents the account-level governmental tax receipts for category ID 931, "Individual Income Taxes." There are only two accounts in this category. It also includes attributes that describe the values' change from the previous year.

getReceiptAggregateBack to Top

Description

getReceiptAggregate is used for obtaining sums. getReceiptAggregate works like getBudgetAccount, but returns cumulative totals by agency, bureau, function or subfunction.

Example Calls

Parameters

getReceiptAggregate accepts the same parameters as getBudgetAccount with some small changes.

group
  • function category
  • subfunction subcategory
  • agency
  • bureau
category
function category
Integer ID for category
0 (all categories)
subfunction subcategory
Integer ID for subcategory
0 (all subcategories)
income
Not supported by this method.

Example Response

http://www.whatwepayfor.com/api/getReceiptAggregate?year=2007&group=category&showExtra=1

<?xml version="1.0" encoding="ISO-8859-1"?><response>
  <item categoryID="931" category="Individual Income Taxes" year="2007" amounti="1163472000" perCapitaI="3.857923" gdpP="0.000082" />
  <item categoryID="932" category="Corporation Income Taxes" year="2007" amounti="370243000" perCapitaI="1.227678" gdpP="0.000026" />
  <item categoryID="933" category="Social Insurance Taxes and Contributions" year="2007" amounti="869607000" perCapitaI="2.883505" gdpP="0.000061" />
  <item categoryID="934" category="Excise Taxes" year="2007" amounti="65069000" perCapitaI="0.215760" gdpP="0.000004" />
  <item categoryID="935" category="Estate and Gift Taxes" year="2007" amounti="26044000" perCapitaI="0.086359" gdpP="0.000001" />
  <item categoryID="936" category="Customs Duties" year="2007" amounti="26010000" perCapitaI="0.086246" gdpP="0.000001" />
  <item categoryID="937" category="Misc. Governmental Receipts" year="2007" amounti="47556000" perCapitaI="0.157690" gdpP="0.000003" />
</response>

Here we're receiving cumulative totals for all receipts, as grouped by category. Each <item> represents a category of receipts, of which there are 7.

getPopulationBack to Top

Description

This method retrieves the national population by year.

Example Calls

Parameters

year
Year in YYYY
2010

Example Response

Here's an example of the type of response you can expect from a call to getPopulation.

http://www.whatwepayfor.com/api/getPopulation

 
<?xml version="1.0" encoding="ISO-8859-1"?><response>
	<item YEAR_I="2010" AMOUNT_I="309050816" CHANGE_I="2044266" CHANGE_P="0.0067" ANNUAL_GDP_PER_CAPITA_I="47436" TOTAL_DEBT_PER_CAPITA_I="43881" />
</response>
amount_i
Total population for the given year.
change_i
Change in total population from the previous year.
change_p
Change in total population from the previous year as a percent.
annual_gdp_per_capita_i
GDP broken down as an amount per person.
total_debt_per_capita_i
National debt broken down as an amount per person.

getGDPBack to Top

Description

This method retrieves the gross domestic product (the measure of economic activity) by year.

Example Calls

Parameters

year
Year in YYYY
2010

Example Response

Here's an example of the type of response you can expect from a call to getGDP.

http://www.whatwepayfor.com/api/getGDP

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
	  <item YEAR_I="2010" AMOUNT_I="14660200000000" CHANGE_I="541200000000" CHANGE_P="0.0383" PER_CAPITA_I="47436" DEBT_P="0.9251" />
</response>
amount_i
Total GDP for the given year.
change_i
Change in total GDP from the previous year.
change_p
Change in total GDP from the previous year as a percent.
per_capita_i
GDP broken down as an amount per person.
debt_p
National debt broken down as a percentage of the GDP.

getDebtBack to Top

Description

This method retrieves the cumulative national debt during a given year.

Example Calls

Parameters

year
Year in YYYY
2010

Example Response

Here's an example of the type of response you can expect from a call to getDebt.

http://www.whatwepayfor.com/api/getDebt

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
	  <item YEAR_I="2010" AMOUNT_I="13561623030892" CHANGE_I="1651794027380" CHANGE_P="0.1387" GDP_P="0.9251" PER_CAPITA_I="43881" />
</response>
amount_i
Cumulative national debt at the time of the given year.
change_i
Change in total national debt from the previous year.
change_p
Change in total national debt from the previous year as a percent.
per_capita_i
National debt broken down as an amount per person.
gdp_p
GDP broken down as a percent of national debt

getTaxRatesBack to Top

Description

This method retrieves the income tax brackets for a given year as well as the medicare and social security taxes.

Example Calls

Parameters

year
Year in YYYY
2010
type
  • 0 Single
  • 1 Married Filing Jointly
  • 2 Married Filing Separately
  • 3 Head of Household
0 (single)

Example Response

Here's an example of the type of response you can expect from a call to getTaxRates.

http://www.whatwepayfor.com/api/getTaxRates?type=0&year=2007

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
	<item YEAR_I="2007" BRACKET_P="0.10" LOWER_WAGE_I="0" UPPER_WAGE_I="7825" TAX_TYPE_N="Single" SS_EMP_P="0.062" SS_SELF_EMP_P="0.124" SS_MAX_I="97500" HI_EMP_P="0.015" HI_SELF_EMP_P="0.029" />
	<item YEAR_I="2007" BRACKET_P="0.15" LOWER_WAGE_I="7825" UPPER_WAGE_I="31850" TAX_TYPE_N="Single" SS_EMP_P="0.062" SS_SELF_EMP_P="0.124" SS_MAX_I="97500" HI_EMP_P="0.015" HI_SELF_EMP_P="0.029" />
	<item YEAR_I="2007" BRACKET_P="0.25" LOWER_WAGE_I="31850" UPPER_WAGE_I="77100" TAX_TYPE_N="Single" SS_EMP_P="0.062" SS_SELF_EMP_P="0.124" SS_MAX_I="97500" HI_EMP_P="0.015" HI_SELF_EMP_P="0.029" />
	<item YEAR_I="2007" BRACKET_P="0.28" LOWER_WAGE_I="77100" UPPER_WAGE_I="160850" TAX_TYPE_N="Single" SS_EMP_P="0.062" SS_SELF_EMP_P="0.124" SS_MAX_I="97500" HI_EMP_P="0.015" HI_SELF_EMP_P="0.029" />
	<item YEAR_I="2007" BRACKET_P="0.33" LOWER_WAGE_I="160850" UPPER_WAGE_I="349700" TAX_TYPE_N="Single" SS_EMP_P="0.062" SS_SELF_EMP_P="0.124" SS_MAX_I="97500" HI_EMP_P="0.015" HI_SELF_EMP_P="0.029" />
	<item YEAR_I="2007" BRACKET_P="0.35" LOWER_WAGE_I="349700" UPPER_WAGE_I="999999999" TAX_TYPE_N="Single" SS_EMP_P="0.062" SS_SELF_EMP_P="0.124" SS_MAX_I="97500" HI_EMP_P="0.015" HI_SELF_EMP_P="0.029" />
</response>
lower_wage_i
Low end of the bracket.
upper_wage_i
Upper end of the bracket.
bracket_p
Rate of taxation for income that applies to income within the lower and upper wage range.
tax_type_n
Name of filing status type.
ss_emp_p
Rate of income taxation for social security as a percentage.
ss_self_emp_p
Rate of income taxation for social security as a percentage for the self employed.
ss_max_i
The maximum amount of money that the social security income tax rate is applied to. Not returned if there is no maximum.
hi_emp_p
Rate of income taxation for Medicare as a percentage.
hi_self_emp_p
Rate of income taxation for Medicare as a percentage for the self employed.
hi_max_i
The maximum amount of money that the Medicare income tax rate is applied to. Not returned if there is no maximum.

getInflationBack to Top

Description

This method retrieves the average price of consumer goods for a given year.

Example Calls

Parameters

year
Year in YYYY
2010

Example Response

Here's an example of the type of response you can expect from a call to getInflation.

http://www.whatwepayfor.com/api/getInflation

 
<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
	  <item YEAR_I="2010" AVG_PRICE_I="218.0560" AVG_CHANGE_P="0.0160" />
</response>
avg_price_i
Average price of goods for a given year.
avg_change_p
Change in average price from the previous year as a percent.