Header Image for Print
Dataset Banner Image

Dataset API Documentation


USPS Crosswalk API

Getting an Access Token

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

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

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.

  1. zip-tract
  2. zip-county
  3. zip-cbsa
  4. zip-cbsadiv (Available 4th Quarter 2017 onwards)
  5. zip-cd
  6. tract-zip
  7. county-zip
  8. cbsa-zip
  9. cbsadiv-zip (Available 4th Quarter 2017 onwards)
  10. cd-zip
  11. zip-countysub (Available 2nd Quarter 2018 onwards)
  12. 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

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

Code sample

		<script>
		function loadJson() {
		var xhttp = new XMLHttpRequest();
		var url = "https://www.huduser.gov/hudapi/public/usps?type=1&query=22031";
		xhttp.open("GET",url, true);
		xhttp.setRequestHeader("Authorization", "Bearer YOUR_API_KEY")
		xhttp.send();
		xhttp.onreadystatechange = function() {
        if (this.readyState == 4) {
		document.getElementById("demo").innerHTML = xhttp.responseText;
		}
		};
		}
		</script>
	

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 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

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)

 

Response Example

	
		"data":[
		{
		"year": "2018",
		"quarter": "Q1",
		"query": "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
		}, 
		]
		}
		]