USPS Address Validation API (v3) — Node.js/TypeScript Skill

A reusable skill providing patterns and best practices for integrating the USPS Address Validation API v3 in Node.js and TypeScript projects.

Installation

Install this skill into your project using the skills CLI:

npx skills add github.com/HamStudy/usps-address-api-node-skill

What This Skill Covers

• API Setup & Credentials: How to register for USPS developer credentials and configure environment variables
• Library Usage: Patterns for using @balancer-team/usps-v3 for address validation, standardization, city/state lookup, and ZIP code lookup
• OAuth Token Management: Direct API patterns for manual token handling when not using the library
• TypeScript Types: Interfaces and utility types for type-safe API integration
• Common Patterns: Handling partial input, rate limiting, batch validation, and Express/Fastify route integration
• Error Handling: Error codes, HTTP statuses, and recovery strategies
• Address Field Guidance: Field mapping, DPV confirmation UX, Puerto Rico/urbanization handling, PO Boxes, and military addresses

Key Facts

• USPS retired the legacy XML Web Tools API on January 25, 2026
• All address validation now uses the v3 REST API with OAuth 2.0
• Tokens are valid for 8 hours — cache aggressively
• Default rate limit: 60 requests/hour per API
• Two environments: apis.usps.com (production) and apis-tem.usps.com (TEM/test)

Project Structure

usps-address-api/
├── SKILL.md              # Skill manifest and quick reference
├── references/
│   ├── setup.md          # Credentials & account setup
│   ├── library.md        # @balancer-team/usps-v3 usage
│   ├── oauth.md          # Manual OAuth token management
│   ├── types.md          # TypeScript interfaces
│   ├── patterns.md       # Common integration patterns
│   ├── errors.md         # Error codes and handling
│   ├── address-fields.md # Field mapping and special cases
│   └── changelog.md      # API changes and migration notes
└── scripts/              # Optional automation scripts

Requirements

• Node.js 18+
• USPS Developer Portal account with API credentials
• @balancer-team/usps-v3 (recommended) or direct fetch implementation

License

MIT