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/geo/reference/geoidentifiers.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/geo/reference/codes/cou.html
| name | description |
|---|---|
type |
REQUIRED; Must be a number between 1 and 12 depending on the Crosswalk type.
|
query |
REQUIRED; 5 digit USPS ZIP code of the data to retrieve. E.g. 22031 for type 1 to 5 and 11 . |
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);
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.
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
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) |
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) |
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) |
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) |
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
},
]
}
]