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.

getBudgetAccount — Returns account level details.
getBudgetAggregate — Returns cumulative totals by agency, bureau, function or subfunction.
getReceiptAccount — Returns account level receipt details.
getReceiptAggregate — Returns cumulative receipt totals by agency, bureau, category or subcategory.
getPopulation — Returns the national population for each year.
getGDP — Returns national GDP for each year.
getDebt — Returns the cumulative national debt during a given year.
getTaxRates — Returns social security, and Medicare, and federal income tax rate brackets.
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

showExtra

0Omits attributes perCapitaI & gdpP
1Includes attributes perCapitaI & gdpP

showChange

0Omits attributes changei & changep
1Includes attributes changei & changep

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

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.