Mapping IRS 1040 Tax Data with the Zip Code API: A Complete Guide

Introduction

When analyzing local markets, income patterns, or demographic segments, raw IRS data can be a goldmine — but it’s often difficult to interpret and integrate. The IRS 1040 Individual Tax Return dataset contains rich information about how Americans earn and report income across every ZIP code, yet working directly with these files requires significant data wrangling.

That’s where the Zip Code API from Metadapi comes in. Our API simplifies access to this information by mapping key IRS 1040 fields to our SOI (Statistics of Income) endpoint. Instead of downloading massive spreadsheets, decoding variable names and cleaning data, developers and analysts can pull precise tax-related metrics for any U.S. ZIP code in seconds.

This guide walks you through how the IRS 1040 data is mapped within the Zip Code API, what each field represents, and how to use it effectively for your projects.

Understanding the Source: IRS 1040 Data

The IRS releases anonymized, aggregated data each year based on the Form 1040 — the U.S. Individual Income Tax Return. This dataset summarizes filing activity and income components by ZIP code, giving an unparalleled look into local economic characteristics.

Some examples of what the IRS 1040 data reveals:

• Number of individual tax returns filed per ZIP code

• Total and average Adjusted Gross Income (AGI)

• Number of dependents claimed

• Distribution of returns by income bracket

• Types of income (wages, dividends, self-employment, etc.)

• Total taxable income and total tax paid

For marketers, researchers, and developers, these metrics can reveal income distribution patterns, household size trends, and economic vitality at the community level.

The Zip Code API Mapping

The Zip Code API organizes these IRS metrics into structured, developer-friendly fields that align directly with 1040 variables. Here’s a simplified look at how some of the mappings work:

In the below example, we are going to focus on 4 tax return measures. Taxable Interest, Ordinary Dividends, Total Income and Adjusted Gross Income. (Our dataset includes hundreds of different return metrics, but for this example, we'll focus on only 4 of them). 

The data provided by the IRS is "grouped" into 6 categories based on the size of the adjusted gross income reported:

Size of adjusted gross income Id: 

• 1 = $1 under $25,000 
• 2 = $25,000 under $50,000 
• 3 = $50,000 under $75,000 
• 4 = $75,000 under $100,000 
• 5 = $100,000 under $200,000 
• 6 = $200,000 or more

Our API documentation includes the mapping reference to both the IRS variable name as well as the Tax form box it relates to.  For example, to get AGI (Adjusted Gross Income) we look at field adjustedGrossIncome in the documentation and we find the following information: 

From there we know that the AGI is related to variable A00100 and you can find this amount on the tax form 1040 Box 11

Looking at the other field documentation, we can find:

We found the right fields we are interested in. Now it's time to call the API, using the following endpoint (only for year 2022):

https://global.metadapi.com/zipc/v1/zipcodes/90210/soi?year=2022

The JSON response includes all the attributes provided by the IRS, for simplicity we'll format the result in an easy to read table (amounts are in '000)

From this result we can now produce all types of analytics or applications that leverage this data.  

Instead of handling raw column codes like A00200 or N02650, you get intuitive JSON fields ready to integrate into your dashboards, reports, or applications.

Why This Mapping Matters

1. Time Savings for Developers

The IRS raw data is extremely detailed but not immediately usable. It requires decoding hundreds of field codes and applying proper weighting. The Zip Code API abstracts all of this complexity, letting you access IRS-sourced data in seconds.

2. Consistent Field Definitions

Every field in the API corresponds to an exact IRS definition. That means your calculations and visualizations remain accurate and consistent with official government data.

3. Geographic Precision

Since the dataset is ZIP code–based, you can zoom into highly localized areas — ideal for comparing neighborhoods, sales territories, or marketing zones.

4. Use Cases Across Industries

• Marketing & Advertising: Target areas by income level or number of dependents.

• Real Estate: Identify ZIP codes with higher disposable income or family density.

• Finance & Lending: Evaluate borrower risk by local average AGI and tax liability.

• Public Policy & Research: Measure income inequality or economic growth by region.

Example Queries and Use Cases

Example 1: Compare Income Levels Between Two ZIP Codes

https://global.metadapi.com/zipc/v1/zipcodes/94103/soi
https://global.metadapi.com/zipc/v1/zipcodes/94016/soi

Compare the adjustedGrossIncome and returns fields to measure income concentration between urban and suburban areas.

Example 2: Identify ZIP Codes with High Business Income

Filter by:

"businessOrProfessionalNetIncomeAmount" > 100000000

This helps pinpoint areas with high levels of self-employment or small business activity.

Getting Started with the API

To explore the mappings and documentation:

1. Visit https://www.metadapi.com/API-Products/Zip-Code-API

2. Sign up for a free developer account.

3. Review the IRS Mapping Documentation section to see every 1040 variable available.

4. Use your API key to query any ZIP code for immediate JSON data.

Best Practices for Using IRS-Based Data

• Normalize for Population Size: Always compare ratios (e.g., AGI per return) rather than raw totals when analyzing across ZIP codes.

• Combine with Demographics: Layer in population, or census data for richer insights.

• Respect Data Granularity: IRS data is aggregated to protect privacy, so treat it as indicative rather than exact for individual-level analysis.

Conclusion

The Zip Code API transforms complex IRS 1040 return data into an accessible, structured format that anyone can use — whether you’re a developer integrating financial indicators, a marketer refining audience profiles, or a researcher studying local economies.

By providing clear field mappings between the IRS 1040 dataset and the API’s endpoints, you gain reliable access to official income and tax insights for every ZIP code in the United States — without the need for manual data processing.

Explore the documentation today and start building smarter, data-driven applications powered by accurate, IRS-sourced insights.