Developers

Embedding widgets and using our API are two ways that developers can engage with and build on MIDAAS data.

API

The MIDAAS API returns incomes of different percentiles for the overall population over various geographies. In addition, you can make calls for different subsets of the population based on race, sex, and age groups.

While by default MIDAAS API will respond with data from the most recent 1-Year American Community Survey (2014), you may access quantile and distribution data for as far back as year 2005.

To use the MIDAAS API, sign up for a unique API key through data.gov, the home of U.S. Government's open data. You may use this key to access MIDAAS and data.gov's other APIs.

[GET] /quantiles?[year=?][state=?][race=?][sex=?][agegroup=?][compare=?]

returns the income amounts for each quantile
curl 'https://api.commerce.gov/midaas/quantiles?state=CA&api_key={your_api_key}'
{
  overall: {
    5%: 400,
    10%: 4000,
    20%: 10000,
    30%: 16000,
    40%: 23000,
    50%: 30000,
    60%: 40000,
    70%: 52000,
    80%: 71000,
    90%: 100000,
    95%: 143200,
    99%: 455000
  }
}

[GET] /income/distribution?[year=?][state=?][race=?][sex=?][agegroup=?][compare=?]

returns the income amounts for each quantile
curl 'https://api.commerce.gov/midaas/distribution?state=CA&race=white&agegroup=25-34&sex=male&api_key={your_api_key}'
{
  $20.00k-$30.00k: 0.1261146303655346,
  $120.00k-$130.00k: 0.018000879457209275,
  $450.00k-$460.00k: 0.005737466859976182,
  $160.00k-$170.00k: 0.004153510772184425,
  $180.00k-$190.00k: 0.002701356626896694,
  $110.00k-$120.00k: 0.013195357305735017,
  $220.00k-$230.00k: 0.0006076886021645845,
  $130.00k-$140.00k: 0.011160008724588761,
  $370.00k-$380.00k: 0.0001702927752706897,
  $240.00k-$250.00k: 0.0004910497149928792,
  $380.00k-$390.00k: 0.00006298499907272085,
  $300.00k-$310.00k: 0.00014229944234948042,
  $500.00k-$510.00k: 0.0003919066608969297,
  $540.00k-$550.00k: 0.00009564388748079833,
  $30.00k-$40.00k: 0.12264112430556122,
  $10.00k-$20.00k: 0.11912912741282118,
  $0.00-$10.00k: 0.1194382204638262,
  $60.00k-$70.00k: 0.07218664088169667,
  $80.00k-$90.00k: 0.041483786611488695,
  $70.00k-$80.00k: 0.05156255285199575,
  $50.00k-$60.00k: 0.0887400317491051,
  $90.00k-$100.00k: 0.03705034251009218,
  $320.00k-$330.00k: 0.0015373005329230756,
  $100.00k-$110.00k: 0.032045367861554305,
  $150.00k-$160.00k: 0.011347797332935205,
  $40.00k-$50.00k: 0.10100577712408161,
  $170.00k-$180.00k: 0.0026453699610542755,
  $200.00k-$210.00k: 0.0046107352098975094,
  $140.00k-$150.00k: 0.005612663250702457,
  $190.00k-$200.00k: 0.0012457033149938124,
  $210.00k-$220.00k: 0.0007324922114383091,
  $230.00k-$240.00k: 0.0007453224890271966,
  ($10.00k)-$0.00: 0.00029626277341613137,
  $250.00k-$260.00k: 0.002918304957036066
}

query params

year
four digit year format
"2005", "2006", "2007", "2008", "2009", "2010", "2011", "2012", "2013", "2014"

state
the two-letter postal abbreviation
"AL", "AK", "AR", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY"

race
"white", "african american", "hispanic", "asian"

sex
"male", "female"

agegroup
"18-24", "25-34", "35-44", "45-54", "55-64", "65+"

compare
field to compare against
"state", "race", "sex", "agegroup"

Widgets

These prebuilt visualizations, which harness Census data, will make it easier for developers of all skill-levels to add rich income insights to their sites. Below are two widgets for embedding bar charts and maps that pull data from the MIDAAS API.

Bar Chart

This visualization allows users to explore income distributions across different geographies by categories (race, sex, and age groups). Want to learn more about the income distribution in your home state or other states? This tool is for you.

embed on your site:

<link rel="stylesheet" href="https://midaas.commerce.gov/assets/css/midaas.min.css">
<link rel="stylesheet" href="https://midaas.commerce.gov/assets/js/key.js">
<script src="https://midaas.commerce.gov/assets/js/midaas.min.js"></script>
<div id="chart1"></div>
<script>
window.Ag.config = {"chart1":{"title":"Explore Income Distributions","type":"bar","dataRequester":{"type":"IncomeQuantilesCompare","query":{"compare":"overall","compareRegion":"US"}},"ui":{"compare":true,"compareRegion":true}}}
</script>

Map

This visualization allows users to explore income distributions across the US at different percentiles by categories (Race, Gender, and Age Groups). Want to know what the 1% is in different states? Want to know what the median individual income is in different states? This tool is for you.

embed on your site:

<link rel="stylesheet" href="https://midaas.commerce.gov/assets/css/midaas.min.css">
<link rel="stylesheet" href="https://midaas.commerce.gov/assets/js/key.js">
<script src="https://midaas.commerce.gov/assets/js/midaas.min.js"></script>
<div id="chart2"></div>
<script>
window.Ag.config = {"chart2":{"title":"Explore Income Distribution Map","type":"map","dataRequester":{"type":"IncomeQuantilesCompare","query":{"compare":"state","compareQuantile":50}},"ui":{"compare":true,"compareQuantile":true}}}
</script>