Developer Reference
USPS Post Office & Mailbox Lookup
Find any of 98,859 USPS post offices and mailbox locations across the US - search by state, ZIP, or city, or find nearby locations, all with GPS coordinates. Free to use, plus a REST API for batch lookups and coverage from your own app.
/api/usps-location?state=:state&zip=:zip&city=:city
USPS Locations by State, ZIP, or City
Look up USPS post offices and mailbox locations by state code, ZIP code, or city. Returns name, address, phone, and GPS coordinates.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
state
optional
|
string
|
2-letter state code (e.g., CA, NY). Required if zip not provided. |
zip
optional
|
string
|
ZIP code. Takes priority over state if both provided. |
city
optional
|
string
|
City name. Used with state to filter by city. |
Response Fields
| Field | Type | Description |
|---|---|---|
success
|
boolean
|
Indicates whether the request succeeded |
state
|
string
|
The queried state code |
total
|
integer
|
Number of locations returned |
locations[].name
|
string
|
Location name (e.g., Post Office, Public Collection Box) |
locations[].address
|
string
|
Street address |
locations[].city
|
string
|
City name |
locations[].state
|
string
|
State code |
locations[].zip
|
string
|
ZIP code |
locations[].phone
|
string
|
Phone number (null if unavailable) |
locations[].coordinates
|
object
|
GPS latitude and longitude |
Code Examples
curl "https://freightapis.dev/api/usps-location?state=CA&city=LOS+ANGELES" \
-H "Authorization: Bearer YOUR_API_KEY"/api/usps-location/search?q=:query
Search USPS Locations
Full-text search across location names, addresses, and cities. Results are paginated.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
q
required
|
string
|
Search query (min 2 characters) |
page
optional
|
integer
|
Page number (default: 1) |
Response Fields
| Field | Type | Description |
|---|---|---|
success
|
boolean
|
Indicates whether the request succeeded |
query
|
string
|
The search query echoed back |
locations[].id
|
integer
|
Internal location ID |
locations[].name
|
string
|
Post office name |
locations[].address
|
string
|
Street address |
locations[].city
|
string
|
City |
locations[].state
|
string
|
2-letter state code |
locations[].zip
|
string
|
ZIP code |
locations[].phone
|
string
|
Phone number |
locations[].coordinates
|
object
|
{ latitude, longitude } |
total
|
integer
|
Total number of matching results |
currentPage
|
integer
|
Current page number |
totalPages
|
integer
|
Total number of pages |
Code Examples
curl "https://freightapis.dev/api/usps-location/search?q=downtown" \
-H "Authorization: Bearer YOUR_API_KEY"/api/usps-location/nearby?lat=:lat&lng=:lng&radius=:radius
Nearby USPS Locations
Find USPS locations near a GPS coordinate. Returns results sorted by distance with Haversine-calculated miles.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
lat
required
|
number
|
Latitude of the center point |
lng
required
|
number
|
Longitude of the center point |
radius
optional
|
number
|
Search radius in miles (default: 10, max: 100) |
page
optional
|
integer
|
Page number (default: 1) |
Response Fields
| Field | Type | Description |
|---|---|---|
locations[].distanceMiles
|
number
|
Distance from center point in miles |
center
|
object
|
Center point coordinates |
radiusMiles
|
number
|
Search radius used |
Code Examples
curl "https://freightapis.dev/api/usps-location/nearby?lat=40.7128&lng=-74.0060&radius=5" \
-H "Authorization: Bearer YOUR_API_KEY"/api/usps-location/coverage
USPS Coverage Statistics
Returns aggregate statistics: total locations and breakdown by state.
Response Fields
| Field | Type | Description |
|---|---|---|
success
|
boolean
|
Indicates whether the request succeeded |
totalLocations
|
integer
|
Total number of USPS locations |
byState
|
array
|
[ { state, count } ] |
Code Examples
curl "https://freightapis.dev/api/usps-location/coverage" \
-H "Authorization: Bearer YOUR_API_KEY"/api/usps-location/batch
Batch State Lookup
Retrieve USPS locations for multiple states in a single request. Maximum 20 states per request (50 for Enterprise).
Request Body
| Parameter | Type | Description |
|---|---|---|
states
required
|
string[]
|
Array of 2-letter state codes. Max 20 for Pro, 50 for Enterprise. |
Response Fields
| Field | Type | Description |
|---|---|---|
success
|
boolean
|
Indicates whether the request succeeded |
results
|
object
|
Map of key to a per-key result: { total, locations[] } keyed by 2-letter state code |
summary
|
object
|
Aggregate counts for the request |
Code Examples
curl -X POST "https://freightapis.dev/api/usps-location/batch" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"states": ["CA", "NY", "TX"]}'USPS Location Lookup - FAQ
How do I find a USPS post office or mailbox?
Search by state, ZIP code, or city, or run a nearby (radius) search. FreightAPIs covers 98,859 USPS post office and mailbox locations and returns GPS coordinates instantly - free to use, with a REST API for programmatic and batch queries.
Is the USPS location lookup free?
Yes. Location lookup is free for all plans. The Free tier includes 20 API calls per month; paid plans raise the monthly quota for higher-volume queries.
How many USPS locations are covered?
FreightAPIs covers 98,859 USPS post office and mailbox locations across the United States, with nearby search and batch lookups of up to 20 items per request (50 for Enterprise).