Register for OAuth 2.0 client credentials on the USPS Developer Portal at developers.usps.com; the legacy Web Tools XML API was retired on 25 January 2026 — all new integrations must use the v3 REST API.
Obtain an access token by POSTing to the USPS OAuth token endpoint with your client ID and client secret using the client_credentials grant type; tokens are valid for 8 hours and have granular scope support.
Send a GET request to https://api.usps.com/addresses/v3/address with query parameters including streetAddress, city, state, and ZIPCode; the API returns the standardized USPS delivery address and the 11-digit delivery point ZIP+4 code.
Parse the response: the returned address fields represent the USPS-standardized form; if the address is undeliverable the response includes an error object with a descriptive code.
For ZIP-to-city/state lookups, call the city-and-state endpoint with a ZIPCode parameter; for city-and-state to ZIP lookups, supply city and state — these are separate endpoints within the Addresses v3 API.
Implement exponential back-off and respect the default rate limit of 60 requests per hour; request a rate limit increase through the developer portal if your volume exceeds this threshold.
Known gotchas
The Web Tools XML API is permanently retired as of January 2026 — any code using the older webservices.usps.com base URL will return errors; migrate to developers.usps.com endpoints before that date.
The default rate limit is 60 requests per hour (approximately 1 per minute), which is very low for bulk address validation — request a higher tier before running large batch jobs.
OAuth tokens expire after 8 hours; a long-running batch that does not refresh the token mid-run will fail partway through with a 401 — implement proactive token refresh logic.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp