USPS v3 Migration Guide:
Node.js & Python SDK

pip install usps-v3

# CI-backed coverage, OAuth caching, USPS workflow modules
# Automatic OAuth token caching
# snake_case → camelCase translation
# httpx + file-based token cache

PyPI · GitHub

npm install usps-v3

// Full TypeScript type definitions
// Automatic OAuth token caching
// Native fetch, zero dependencies
// ESM and CommonJS support

npm · GitHub

# ❌ This no longer works
from usps import USPSApi, Address

usps = USPSApi("YOUR_USER_ID")

address = Address(
    name="White House",
    address_1="1600 Pennsylvania Ave NW",
    city="Washington",
    state="DC",
    zipcode="20500",
)

result = usps.validate_address(address)
print(result.result)
# → ConnectionError: API endpoint dead

# ✓ Current — works today
from usps_v3 import USPSClient

client = USPSClient(
    client_id="your_consumer_key",
    client_secret="your_consumer_secret",
)

result = client.addresses.validate(
    street_address="1600 Pennsylvania Ave NW",
    city="Washington",
    state="DC",
    zip_code="20500",
)
print(result.address.street_address)
print(result.address.zip_code)
# → 1600 PENNSYLVANIA AVE NW
# → 20500-0005

// ❌ This no longer works
const USPS = require('usps-webtools');
const usps = new USPS({
  userId: 'YOUR_USER_ID'
});

usps.verify({
  street1: '1600 Pennsylvania Ave NW',
  city: 'Washington',
  state: 'DC',
  zip: '20500',
}, (err, result) => {
  console.log(result);
});
// → ECONNREFUSED

// ✓ Current — works today
import { USPSClient } from 'usps-v3';

const client = new USPSClient({
  clientId: 'your_consumer_key',
  clientSecret: 'your_consumer_secret',
});

const result = await client.addresses.validate({
  streetAddress: '1600 Pennsylvania Ave NW',
  city: 'Washington',
  state: 'DC',
  zipCode: '20500',
});
console.log(result.address.streetAddress);
console.log(result.address.zipCode);
// → 1600 PENNSYLVANIA AVE NW
// → 20500-0005

# ❌ Dead
result = usps.track("9400111899223")
print(result.result)

# ✓ Current
result = client.tracking.get("9400111899223")
print(result.status_summary)
print(result.tracking_events[0].event_type)
# → "Your item has been delivered"

// ❌ Dead
usps.track('9400111899223',
  (err, result) => {
    console.log(result);
});

// ✓ Current
const result = await client.tracking.get(
  '9400111899223'
);
console.log(result.statusSummary);
console.log(result.trackingEvents[0]);

# ❌ Dead — used RateV4 XML endpoint
# No Python SDK for this existed
# Most devs used raw XML with requests
xml = """<RateV4Request USERID="...">
  <Package ID="1">
    <Service>PRIORITY</Service>
    <ZipOrigination>94105</ZipOrigination>
    <ZipDestination>20500</ZipDestination>
    <Pounds>1</Pounds>
    <Ounces>0</Ounces>
  </Package>
</RateV4Request>"""

# ✓ Current
rates = client.prices.rate(
    origin_zip="94105",
    destination_zip="20500",
    weight=16,  # ounces
    mail_class="PRIORITY_MAIL",
    processing_category="MACHINABLE",
)
print(f"${rates.total_price}")
# → $X.XX (actual rate varies by zone/weight)

// ❌ Dead — callback-based XML
usps.pricingRateV4({
  Service: 'PRIORITY',
  ZipOrigination: '94105',
  ZipDestination: '20500',
  Pounds: 1, Ounces: 0,
}, (err, result) => {
  console.log(result.Postage);
});

// ✓ Current — async/await, typed
const rates = await client.prices.rate({
  originZip: '94105',
  destinationZip: '20500',
  weight: 16,  // ounces
  mailClass: 'PRIORITY_MAIL',
  processingCategory: 'MACHINABLE',
});
console.log(`${rates.totalPrice}`);
// → $X.XX (actual rate varies by zone/weight)

standards = client.standards.get(
    origin_zip="94105",
    destination_zip="20500",
    mail_class="PRIORITY_MAIL",
    accept_date="2026-03-10",
)
print(standards.delivery_date)
# → 2026-03-13

const standards = await client.standards.get({
  originZip: '94105',
  destinationZip: '20500',
  mailClass: 'PRIORITY_MAIL',
  acceptDate: '2026-03-10',
});
console.log(standards.deliveryDate);
// → 2026-03-13