Skip to main content

USPS Dataset API Documentation

HUD.GOV HUDUser.gov
Dataset Banner Image

USPS Dataset API Documentation

    Dataset/USPS Dataset API Documentation

USPS NCWM Data API

Click here to view Terms of Service of the HUD User API

Getting an Access Token

Follow these steps to create an account and get an access token:

  1. If you already have an account, Login and update the datasets you want to access in your account.
  2. Otherwise Sign up for an account and select the Datasets API you want to access.
  3. Confirm your account, if it's new - Check your inbox for a confirmation email from HUD User.
  4. After log in, Get an access token by clicking on Create New Token.
  5. Use it in the Authorization: Bearer header to make API calls.

Base URL

The base URL for all USPS NCWM Data API endpoints is 

https://www.huduser.gov/hudapi/public/uspsncwm

Response Codes

One of the following response codes will be returned with every request:

code description

200

Request was successful

400

An invalid value was specified for one of the query parameters in the request URI.

401

Authentication failure

403

Not allowed to access this dataset API because you have not registered for it.

404

No data found using '(value you entered)'

405

Unsupported method, only GET is supported

406

Unsupported Accept Header value, must be application/json

500

Internal server error occurred

Input parameters

These parameters appear after a question mark (?) in the endpoint. They are separated using the ampersand (&) character.

name description

year

OPTIONAL; Year of the data to retrieve. Default is the latest year.

month

OPTIONAL; Month of the data to retrieve. Default is the latest month.

type

REQUIRED; Must be a number between 1 and 6 depending on the type of data.

1 - USPS Standardized Data
2 - Tenant Data
3 - Decennial Census Data
4 - American Community Survey Data
5 - Cumulative LIHTC
6 - Economic Development

tractid

Required if stateid is not provided.; 11-digit unique identifier for small geographic areas used by the U.S. Census Bureau.

stateid

Required if tractid is not provided.; 2-digit FIPS code uniquely identifying a U.S. state or equivalent territory, as used by the U.S. Census Bureau.

The table below shows the path to get census tract id.

To get.. Endpoint Lookup example

Census Tract ID

uspsncwm/lookup/tractid

uspsncwm/lookup/tractid?statename={statename}
Retrieves Census Tract IDs. The {statename} parameter is optional. If omitted, all Tract IDs will be returned.
Example: uspsncwm/lookup/tractid?statename=Florida

Example Call

Pass the accesstoken in the header to make API calls. An example using the command-line client curl is shown below: 

curl -H "Authorization: Bearer YOUR_API_KEY" -G -d 'type=1&year=2024&month=3&tractid=11001008410' https://www.huduser.gov/hudapi/public/uspsncwm

API Tester

Use the API Tester to make API calls to USPS Dataset. The API Tester requires an access token. If you have forgotten or do not have a token, click here.










Response Example for USPS Standardized Data

API call: 

https://www.huduser.gov/hudapi/public/uspsncwm?type=1&year=2025&month=3&tractid=51009010201

{
    "year": "2025",
    "month": 3,
    "type": "1",
    "results": [
        {
            "TRACT ID": "51009010201",
            "STATE_GEOID": "51",
            "COUNTY_GEOID": "009",
            "STCNTY": "51009",
            "STATE_NAME": "Virginia",
            "COUNTY_NAME": "Amherst County",
            "CBSA_CODE": "31340",
            "CBSA_TITLE": "Lynchburg, VA",
            "METRO_MICRO_AREA": "Metropolitan Statistical Area",
            "METRO_DIVISION_CODE": null,
            "METRO_DIVISION_TITLE": null,
            "CENTRAL_OUTLYING_COUNTY": "Central",
            "R_SUM_TOT_RES": "1671.0",
            "R_SUM_RES_NO_STAT": "156.0",
            "R_SUM_S_VAC_RES": "0.0",
            "R_SUM_L_VAC_RES": "0.0",
            "R_SUM_TOT_BUS": "84.0",
            "R_SUM_BUS_NO_STAT": "19.0",
            "R_SUM_S_VAC_BUS": "0.0",
            "R_SUM_L_VAC_BUS": "0.0",
            "R_SUM_TOT_OTH": "48.0",
            "R_SUM_OTH_NO_STAT": "0.0",
            "R_SUM_S_VAC_OTH": "0.0",
            "R_SUM_L_VAC_OTH": "0.0",
            "C_SUM_TOT_RES": "0.0",
            "C_SUM_RES_NO_STAT": "0.0",
            "C_SUM_S_VAC_RES": "0.0",
            "C_SUM_L_VAC_RES": "0.0",
            "C_SUM_TOT_BUS": "0.0",
            "C_SUM_BUS_NO_STAT": "0.0",
            "C_SUM_S_VAC_BUS": "0.0",
            "C_SUM_L_VAC_BUS": "0.0",
            "C_SUM_TOT_OTH": "4.0",
            "C_SUM_OTH_NO_STAT": "0.0",
            "C_SUM_S_VAC_OTH": "0.0",
            "C_SUM_L_VAC_OTH": "0.0",
            "TOTAL_RESIDENTIAL_ADDRESSES": "1677.0",
            "TOTAL_BUSINESS_ADDRESSES": "84.0",
            "TOTAL_OTHER_ADDRESSES": "55.0",
            "SHARE_SHORT_TERM_VAC_RES": "0.0",
            "SHARE_SHORT_TERM_VAC_BUS": "0.0",
            "SHARE_SHORT_TERM_VAC_OTHER": "0.0",
            "SHARE_LONG_TERM_VAC_RES": "0.0",
            "SHARE_LONG_TERM_VAC_BUS": "0.0",
            "SHARE_LONG_TERM_VAC_OTHER": "0.0",
            "SHARE_COMPOSITE_VACANT_RES": "9.3019999999999996",
            "SHARE_COMPOSITE_VACANT_BUS": "22.619",
            "SHARE_COMPOSITE_VACANT_OTH": "0.0",
            "Active_Residential_Addresses": "1521.0",
            "STV_RESIDENTIAL_ADDRESSES": "0.0",
            "LTV_RESIDENTIAL_ADDRESSES": "0.0",
            "NO_STAT_RESIDENTIAL_ADDRESSES": "156.0",
            "ACTIVE_BUSINESS_ADDRESSES": "65.0",
            "STV_BUSINESS_ADDRESSES": "0.0",
            "LTV_BUSINESS_ADDRESSES": "0.0",
            "NO_STAT_BUSINESS_ADDRESSES": "19.0",
            "ACTIVE_OTHER_ADDRESSES": "55.0",
            "STV_OTHER_ADDRESSES": "0.0",
            "LTV_OTHER_ADDRESSES": "0.0",
            "NO_STAT_OTHER_ADDRESSES": "0.0",
            "U_SUM_TOT_RES": "6.0",
            "U_SUM_RES_NO_STAT": "0.0",
            "U_SUM_S_VAC_RES": "0.0",
            "U_SUM_L_VAC_RES": "0.0",
            "U_SUM_TOT_BUS": "0.0",
            "U_SUM_BUS_NO_STAT": "0.0",
            "U_SUM_S_VAC_BUS": "0.0",
            "U_SUM_L_VAC_BUS": "0.0",
            "U_SUM_TOT_OTH": "3.0",
            "U_SUM_OTH_NO_STAT": "0.0",
            "U_SUM_S_VAC_OTH": "0.0",
            "U_SUM_L_VAC_OTH": "0.0"
        }
    ]
}

Response Example for Tenant Data

API call: 

https://www.huduser.gov/hudapi/public/uspsncwm?type=2&year=2024&month=9&tractid=51009010201

{
    "year": "2024",
    "month": 9,
    "type": "2",
    "results": [
        {
            "TRACT ID": "51009010201",
            "STATE_GEOID": "51",
            "COUNTY_GEOID": "510",
            "STCNTY": "51009",
            "STATE_NAME": "Virginia",
            "COUNTY_NAME": "Amherst County",
            "CBSA_CODE": "31340",
            "CBSA_TITLE": "Lynchburg, VA",
            "METRO_MICRO_AREA": "Metropolitan Statistical Area",
            "METRO_DIVISION_CODE": "",
            "METRO_DIVISION_TITLE": "",
            "CENTRAL_OUTLYING_COUNTY": "Central",
            "PUBLIC_HOUSING": "0.0",
            "TENANT_BASED_VOUCHER": "16.0",
            "PROJECT_BASED_VOUCHER": "0.0",
            "HOUSING_CHOICE_VOUCHER": "0.0",
            "OTHER": "0.0",
            "PROJECT_BASED_SECTION_8": "0.0",
            "SECTION_202": "0.0",
            "SECTION_811": "0.0"
        }
    ]
}

Response Example for Decennial Census Data

API call: 

https://www.huduser.gov/hudapi/public/uspsncwm?type=3&year=2020&month=3&tractid=51009010201

{
    "year": "2020",
    "month": 3,
    "type": "3",
    "results": [
        {
            "TRACT ID": "51009010201",
            "HU": "1861.0",
            "HU_OCCUPIED": "1678.0",
            "HU_VACANT": "183.0",
            "HU_OCCUPIED_OWNER": "1199.0",
            "HU_OCCUPIED_RENTER": "479.0",
            "POPULATION": "4398.0",
            "AIAN_NH": "25.0",
            "ASAIN_PI_NH": "45.0",
            "BLACK_NH": "750.0",
            "HISPANIC": "153.0",
            "OTH_MUL_NH": "202.0",
            "WHITE_NH": "3207.0",
            "SUM_OF_SQUARED_RATES": "0.43573652995770318"
        }
    ]
}

Response Example for American Community Survey Data

API call: 

https://www.huduser.gov/hudapi/public/uspsncwm?type=4&year=2020&month=6&tractid=51009010201

{
    "year": "2020",
    "month": 6,
    "type": "4",
    "results": [
        {
            "TRACT ID": "51009010201",
            "SURVEY": "ACS_2018_2022",
            "TOTAL_5": "4612",
            "TOTAL_5_MOE": null,
            "ENG": "4424",
            "ENG_MOE": "400",
            "TOTAL_HU": "4105",
            "TOTAL_HU_MOE": "402",
            "POV": "478",
            "POV_MOE": "115",
            "TOTAL_25": "3193",
            "TOTAL_25_MOE": "301",
            "COLLEGE": "1018",
            "COLLEGE_MOE": "417",
            "TOTAL": "4789",
            "TOTAL_MOE": null,
            "FB": "133",
            "FB_MOE": "90",
            "COLLEGE_EDUCATED": "0.31882242405261507",
            "COLLEGE_EDUCATED_MIN": "0.17200915855752719",
            "COLLEGE_EDUCATED_MAX": "0.49619640387275243",
            "FOREIGN_BORN": "2.7771977448319066E-2",
            "FOREIGN_BORN_MIN": "8.2851637764932567E-3",
            "FOREIGN_BORN_MAX": "5.0820419325432999E-2",
            "POVERTY_RATE": "0.11644336175395859",
            "POVERTY_RATE_MIN": "8.0541380075438207E-2",
            "POVERTY_RATE_MAX": "0.1601404266810694",
            "ENGLISH_HOME": "0.95923677363399829",
            "ENGLISH_HOME_MIN": "0.80191311279394184",
            "ENGLISH_HOME_MAX": "1.0"
        }
    ]
}

Response Example for Cumulative LIHTC Data

API call: 

https://www.huduser.gov/hudapi/public/uspsncwm?type=5&year=2023&month=12&tractid=51009010201

{
    "year": "2023",
    "month": 12,
    "type": "5",
    "results": [
        {
            "TRACT ID": "51009010201",
            "LIHTC_PLACED_IN_SERVICE": "116"
        }
    ]
}

Response Example for Economic Development

API call: 

https://www.huduser.gov/hudapi/public/uspsncwm?type=6&tractid=51009010201

{
    "type": "6",
    "results": [
        {
            "TRACT ID": "51009010201",
            "QOZ_2020": null,
            "QCT": "Not Qualified",
            "NMTC": "Not Qualified",
            "USPS_CHANGE": "OUTSIDE THRESHOLD"
        }
    ]
}