Area Median Income API Calculations

Area Median Income API Percentage

Purpose: Calculates HUD Area Median Income (AMI) as a percentage based on the HUD Median Income dataset. 

This calculates the Area Median Income on a Statewide Level and on a County/Entity/MetroArea level. The more local number will require you to have a FIPS code set in your county lookup or GIS available in New England. FIPS codes are unique codes on the County lookup. 

Cost: There is no cost to use this module.

Related: Manually maintained AMI Tables. But all the cool kids use the API.

Note: This is a different feature than Median Income, which some states have. The similar names are not our fault.

In this article:

• Setup
• Notes on Block Placement
• Block Configuration
• Use in New England
• Limitations
• Notes on the Calculation (including an example)
• Situations with No Income
• Why Does my AMI Percentage look Lower than my Band?

Setup 

Setting up AMI API calculations requires three steps:

1. Obtaining a HUD API key by following the instructions on the HUD FRM IL Dataset API Documentation page. 
2. Entering the HUD API key on the Admin -> Process Settings page and enabling the HUD Median Income Percentage API. 
3. Adding the HUD Median API block to your intake process. 

Notes on Block Placement

AMI Percentage is calculated by the block by comparing the matter's intake date, county of residence, and total income to HUD's data.

Therefore to get the calculated default, the block needs to be on a form after State, County of Residence, Household Size, and Income have been saved. The block is typically placed on an intake form, and an auxiliary form for editing/recalculation after a case is opened.

If this is configured, the AMI Poverty Category block gets a checkbox in its configuration to "Use HUD Median Income API". When this is selected, it will set the AMI Poverty Category as a result of the API calculation. The AMI Poverty Category block needs to come after the HUD Median API block or it will take the place of the HUD Median API block.

The block will cause an error on case profile pages. Only use it on forms.

Block Configuration

The HUD Median API block has a configuration option: "Match the intake year for HUD calculation". This is enabled by default.

Unchecking that option will use the previous year in the API call if the intake date on the case is in January, February, or March.

Use in New England

To use this block in New England (Connecticut, Maine, Massachusetts, New Hampshire, Rhode Island, and Vermont), you need to have GIS enabled because HUD divides these into Towns and not Counties. As part of the GIS shapes available, you should have a County Subdivision location that will get automatically populated. The API blocks will use this GIS shape to get the Area Median Income values from the HUD API. The block will look slightly different and show the County Subdivision and the revised FIPS location code.

Limitations

The API only returns results for 2017 and later. Earlier intake dates will result in an error of:

Invalid Year        

Notes on the Calculation

The API takes parameters for the State/Area of Residence and the year (based on the Intake Date). Once the State/County limit is returned, the Total Household Income is compared to the HUD Median Income and a percentage is calculated. Household size is taken into account based on the US HUD PDR-99-02 Notice regarding family size adjustments. The number in the HUD dataset is for a family of 4. For smaller families, 10% is removed per person. For larger families 8% is added.

To test the data, you can go to HUD Income Limits to get the specific data for the correct year and jurisdiction.

Example Calculation

For example, if you have a family of 2 in Middlesex County, NJ, that makes $70,000 annually and applied for services on May 1, 2024, the calculations would like as follows:

Adjustment for 2 person family = 100% - 10% * [household_size] = 80%

State Median Income = $125,300
State Median Income adjusted for 2 person family: $125,300 * 80% =  $100,240
State Median Income Percentage = $70,000 / $100,240 * 100% = 69.8%
State Median Income Band = 50-80%

Area Median Income = $146,200
Area Median Income adjusted for 2 person family: $146,200 * 80% = $116,960
Area Median Income Percentage = $70,000 / $116,960 * 100% = 59.8%
Area Median Income Band = 50-80%

State Median Income Source

Area Median Income Source

Situations with No Income

As of 2024-04-04 on Demo and 2024-04-12 on Live: If Income has not yet been collected, then you will see a message Income has not yet been populated, median income API is unavailable .

If Income was collected but the client reported No Household Income , then the Percentages and bands are all set to 0 or the lowest bracket possible.

If Income has been collected but the client did not provide their income - Income Not Provided , then the percentages and bands are all set to Null or N/A with the message Income has not been provided.

Why Does my AMI Percentage look Lower than my Band?

There are certain jurisdictions that have High Housing Cost adjustments to the AMI Bands that are not present in the Area Median Income number itself. Examples of this include Los Angeles County, CA and New York County, NY. If you refer to the HUD documentation itself, you can see that the 80% number for a family of 4 is $12,300 more than the Area Median Income. This is because the band is adjusted while the AMI itself is not. You can click on the "Click for More Detail" buttons to see the calculations themselves.