FreightAPIs API · 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.

Get API Key ← Overview Download OpenAPI spec Open in ChatGPT↗Open in Claude↗
GET /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
stateoptional string 2-letter state code (e.g., CA, NY). Required if zip not provided.
zipoptional string ZIP code. Takes priority over state if both provided.
cityoptional 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
city string The queried city (when the city parameter is used)
total integer Number of locations returned
locations[].id integer Internal location ID
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 | null 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"

Full-text search across location names, addresses, and cities. Results are paginated.

Query Parameters

Parameter Type Description
qrequired string Search query (min 2 characters)
pageoptional 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"
GET /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
latrequired number Latitude of the center point
lngrequired number Longitude of the center point
radiusoptional number Search radius in miles (default: 10, max: 100)
pageoptional integer Page number (default: 1)

Response Fields

Field Type Description
success boolean Indicates whether the request succeeded
total integer Number of locations within the radius
currentPage integer Current page number
totalPages integer Total number of pages
locations[].id integer Internal location ID
locations[].name string Location name
locations[].address string Street address
locations[].city string City
locations[].state string State code
locations[].zip string ZIP code
locations[].phone string | null Phone number, when listed
locations[].coordinates object { latitude, longitude }
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"
GET /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"
POST /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
statesrequired 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).