USPS Locations - API Docs

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

{
  "success": true,
  "city": "LOS ANGELES",
  "state": "CA",
  "total": 187,
  "locations": [
    {
      "id": 1,
      "name": "Los Angeles Main Post Office",
      "address": "7001 S Central Ave",
      "city": "LOS ANGELES",
      "state": "CA",
      "zip": "90001",
      "phone": "3235864411",
      "coordinates": {
        "latitude": 33.970127,
        "longitude": -118.264015
      }
    }
  ]
}

GET /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)

Code Examples

curl "https://freightapis.dev/api/usps-location/search?q=downtown" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "query": "downtown",
  "locations": [ ... ],
  "total": 45,
  "currentPage": 1,
  "totalPages": 2
}

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

{
  "success": true,
  "center": { "latitude": 40.7128, "longitude": -74.006 },
  "radiusMiles": 5,
  "locations": [
    {
      "id": 42,
      "name": "Wall Street Post Office",
      "address": "73 Pine St",
      "city": "NEW YORK",
      "state": "NY",
      "zip": "10005",
      "phone": "2126680076",
      "coordinates": { "latitude": 40.7073, "longitude": -74.0077 },
      "distanceMiles": 0.39
    }
  ],
  "total": 127,
  "currentPage": 1,
  "totalPages": 6
}

GET /api/usps-location/coverage

USPS Coverage Statistics

Returns aggregate statistics: total locations and breakdown by state.

Code Examples

curl "https://freightapis.dev/api/usps-location/coverage" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "totalLocations": 98859,
  "byState": [
    { "state": "AK", "count": 127 },
    { "state": "AL", "count": 1210 },
    { "state": "CA", "count": 8754 },
    ...
  ]
}

POST /api/usps-location/batch

Batch State Lookup

Retrieve USPS locations for multiple states in a single request. Maximum 10 states per call.

Request Body

Parameter	Type	Description
`states` required	`string[]`	Array of 2-letter state codes (max 10)

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"]}'

{
  "success": true,
  "results": {
    "CA": { "total": 8754, "locations": [ ... ] },
    "NY": { "total": 11200, "locations": [ ... ] },
    "TX": { "total": 4521, "locations": [ ... ] }
  },
  "summary": { "statesRequested": 3, "totalLocations": 24475 }
}