USPS Dataset API Documentation

USPS Crosswalk 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:

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

Terms of Use

No special restrictions or limitations on using the item’s content have been provided.

Base URL

The base URL for all USPS API endpoints is https://www.huduser.gov/hudapi/public/usps

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. You need to provide either zip code or GEOID as input. You may find the following links helpful to find the correct GEOID:
Understanding GEOIDs - https://www.census.gov/programs-surveys/geography/guidance/geo-identifiers.html
For CBSA and CBSA Division code lookup - https://www.census.gov/geographies/reference-files/time-series/demo/metro-micro/delineation-files.html
For County/County Equivalent code - https://www.census.gov/geographies/reference-files/time-series/geo/county-adjacency.html

name	description
type	REQUIRED; Must be a number between 1 and 12 depending on the Crosswalk type. zip-tract zip-county zip-cbsa zip-cbsadiv (Available 4th Quarter 2017 onwards) zip-cd tract-zip county-zip cbsa-zip cbsadiv-zip (Available 4th Quarter 2017 onwards) cd-zip zip-countysub (Available 2nd Quarter 2018 onwards) countysub-zip (Available 2nd Quarter 2018 onwards)
query	REQUIRED; 5 digit USPS ZIP code of the data to retrieve. E.g. 22031 for type 1 to 5 and 11 . or 11 digit unique 2000 or 2010 Census tract GEOID consisting of state FIPS + county FIPS + tract code. Eg: 51059461700 for type 6 or 5 digit unique 2000 or 2010 Census county GEOID consisting of state FIPS + county FIPS. Eg: 51600 for type 7 or 5 digit CBSA code for Micropolitan and Metropolitan Areas Eg: 10380 for type 8 or 5-dgit CBSA Division code which only applies to Metropolitan Areas. Eg: 35614 for type 9 or 4-digit GEOID for the Congressional District which consists of state FIPS + Congressional District code. Eg: 7200 for type 10 or 10-digit GEOID for the County sub Eg: 4606720300 for type 12 or 2-letter state code for state level data - (Available 1st Quarter 2021 onwards for all types , 1 to 12) or The word "All" for the entire file - (Available 1st Quarter 2021 onwards for all types, 1 to 12)
year	Year of the data to retrieve E.g. 2017. Default is latest year. Optional
quarter	Quarter of the year. Number between 1 and 4. Default is latest quarter. Optional

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&query=22031' https://www.huduser.gov/hudapi/public/usps

An example using Python code is shown below:

import pandas as pd
import requests

# return a Pandas Dataframe of HUD USPS Crosswalk values

# Note that type is set to 1 which will return values for the ZIP to Tract file and query is set to VA which will return Zip Codes in Virginia
url = "https://www.huduser.gov/hudapi/public/usps?type=1&query=VA"
token = "YOUR_API_KEY"
headers = {"Authorization": "Bearer {0}".format(token)}

response = requests.get(url, headers = headers)

if response.status_code != 200:
	print ("Failure, see status code: {0}".format(response.status_code))
else: 
	df = pd.DataFrame(response.json()["data"]["results"])	
	print(df);

An example using R script is shown below:

#An R script to Get data from the HUD USPS ZIP Code Crosswalk Files API
library(httr)

key <- "YOUR KEY HERE"
url <- "https://www.huduser.gov/hudapi/public/usps"

# Note that type is set to 1 which will return values for the ZIP to Tract file and query is set to VA which will return Zip Codes in Virginia
response <- httr::GET(url, query = list(type = 1, query = "VA"), add_headers(Authorization = paste("Bearer", key)))

#check for errors
httr::http_error(response)

#access up the output
output <- httr::content(response)

API Tester

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

Example using state as input: Enter type = 1 and query = VA
Response gives all the zip codes in the state of Virginia for type 1.
Query string in this case is: https://www.huduser.gov/hudapi/public/usps?type=1&query=VA

Example using "All" as input: Enter type = 1 and query = All
Response returns all zip codes for type 1.
Query string in this case is: https://www.huduser.gov/hudapi/public/usps?type=1&query=All

Access Token:

type:

query:

year:

quarter:

Response Structure

property	type	description
year	string	Data Year
quarter	string	Quarter of the Data Year
query	string	Zip, Tract, County, CBSA or CD entered as input query
crosswalk_type	string	Type of Crosswalk data
results	array	It is an array of the output data for the requested (input) query
zip/tract/county/cbsa/cbsa_div/cd/county_sub	string	This field name varies depending on the crosswalk type. It could be any one of zip, tract, county, cbsa, cbsa_div, cd or county_sub
geoid	string	Zip, Tract, County, CD or CBSA code
res_ratio	number	The ratio of residential addresses in the ZIP – Tract, County, or CBSA part to the total number of residential addresses in the entire ZIP. (for type 1-5) The ratio of residential addresses in the Zip, Tract, County, or CBSA - ZIP part to the total number of residential addresses in the entire Zip, Tract, County, or CBSA. (for type 6-10)
bus_ratio	number	The ratio of business addresses in the ZIP – Tract, County, or CBSA part to the total number of business addresses in the entire ZIP. (for type 1-5) The ratio of business addresses in the Tract, County, or CBSA – ZIP part to the total number of business addresses in the entire Tract, County, or CBSA. (for type 6-10)
oth_ratio	number	The ratio of other addresses in the ZIP – Tract to the total number of other addresses in the entire ZIP. (for type 1-5) The ratio of other addresses in the Tract, County, or CBSA – ZIP part to the total number of other addresses in the entire Tract, County, or CBSA. (for type 6-10)
tot_ratio	number	The ratio of all addresses in the ZIP – Tract to the total number of all types of addresses in the entire ZIP. (for type 1-5) The ratio of all addresses in the Tract, County, or CBSA-ZIP part to the total number of all types of addresses in the entire Tract, County, or CBSA. (for type 6-10)
city	string	(Available 1st Quarter 2021 onwards for all types)
state	string	(Available 1st Quarter 2021 onwards for all types)

Response Example

	
		"data":[
		{
		"year": "2018",
		"quarter": "Q1",
		"input": "22031",
		"crosswalk_type": "zip-tract",
		"results":  [
		{
		"geoid": "51059461700",
		"res_ratio": 0.174321153,
		"bus_ratio": 0.055795848,
		"oth_ratio": 0.049571020,
		"tot_ratio": 0.152166776
		},
		{
		"geoid": "51059461602,
		"res_ratio": 0.080590010,
		"bus_ratio": 0.229671280,
		"oth_ratio": 0.084842707,
		"tot_ratio": 0.099693587
		},
		{
		"geoid": "51059440202,
		"res_ratio": 0.063426081,
		"bus_ratio": 0.066608997,
		"oth_ratio": 0.077216397,
		"tot_ratio": 0.064620267
		}, 
		]
		}
		]

ABOUT PD&R

RESEARCH & PUBLICATIONS

DATASETS

QUICK LINKS

ABOUT PD&R

RESEARCH & PUBLICATIONS

DATASETS

QUICK LINKS

USPS Dataset API Documentation