The authoritative source is USPS
POST /v1/orders verifies both the recipient and the sender against USPS. If standardization changes the address (e.g. San Francisco → SAN FRANCISCO, or a casing/abbreviation fix), the response includes the corrected version you’ll actually mail to:
The order’s
to field stays as addressed. corrected_to is what USPS will actually deliver to. Quote it back only if you need to display the canonical form.Autocomplete (typeahead)
GET /v1/address/autocomplete?q=... returns candidate addresses as the user types:
enabled is false (with an empty suggestions array) when no geocoding
provider is configured on this deployment — there is no status field on
this endpoint.
Reverse geocode
GET /v1/address/reverse?lat=...&lon=... returns the address nearest a lat/lon — useful for map clicks. Note the parameter is lon, not lng:
{ "enabled": true, "address": {...} }, or { "enabled": false, "address": null } when unconfigured.
Autocomplete and reverse geocoding are convenience only. USPS verification on order creation is the authoritative check. Don’t ship mail off the typeahead without the order’s verification pass.
What failure looks like
An unverifiable address fails the order with an address error in the envelope (acode + next with the USPS-corrected candidate when available), rather than mailing to a guess.