API Reference

Everything you need to integrate with the USPS v3 REST API. Base URL: https://api.revaddress.com

Authentication

All API requests require an API key passed via the X-API-Key header. Keys are prefixed with rv_live_ (production) or rv_test_ (sandbox).

curl -H "X-API-Key: rv_live_your_key_here" \
  https://api.revaddress.com/api/address/validate?street=1600+Pennsylvania+Ave&city=Washington&state=DC&zip=20500

Address Validation

Validate and standardize US addresses using USPS CASS-certified data. Returns DPV confirmation, ZIP+4, and delivery indicators.

GET /api/address/validate
  ?street=1600+Pennsylvania+Ave
  &secondary=Suite+100
  &city=Washington
  &state=DC
  &zip=20500

// Response
{
  "address": {
    "street": "1600 PENNSYLVANIA AVE NW",
    "secondary": "STE 100",
    "city": "WASHINGTON",
    "state": "DC",
    "zip5": "20500",
    "zip4": "0005",
    "dpv": "Y",
    "vacant": "N",
    "deliveryPoint": "00"
  }
}

Package Tracking

Track any USPS package by tracking number. Returns full scan history, delivery status, and estimated delivery date.

GET /api/tracking/9400111899223456789012

// Response
{
  "tracking_number": "9400111899223456789012",
  "status": "Delivered",
  "delivered_at": "2026-03-08T14:22:00Z",
  "location": "WASHINGTON, DC 20500",
  "events": [
    {
      "timestamp": "2026-03-08T14:22:00Z",
      "event": "Delivered, In/At Mailbox",
      "city": "WASHINGTON",
      "state": "DC"
    }
  ]
}

Label Creation

Create USPS shipping labels with full address validation, rate shopping, and PDF/PNG output. Requires Growth plan or higher.

POST /api/labels/create
Content-Type: application/json

{
  "from": {
    "name": "RevAddress",
    "street": "123 Sender St",
    "city": "New York",
    "state": "NY",
    "zip": "10001"
  },
  "to": {
    "name": "Recipient",
    "street": "456 Receiver Ave",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001"
  },
  "service": "PRIORITY_MAIL",
  "weight_oz": 16
}

// Response
{
  "label_id": "lbl_abc123",
  "tracking_number": "9205590164917312345678",
  "label_url": "https://api.revaddress.com/labels/lbl_abc123.pdf",
  "rate": {
    "amount": 8.70,
    "currency": "USD"
  }
}

Domestic Prices

Get live USPS pricing for all domestic service types. Compare Priority Mail, First Class, Ground Advantage, and more.

GET /api/prices/domestic
  ?origin_zip=10001
  &destination_zip=90001
  &weight_oz=16

// Response
{
  "rates": [
    {
      "service": "PRIORITY_MAIL",
      "price": 8.70,
      "delivery_days": 2
    },
    {
      "service": "GROUND_ADVANTAGE",
      "price": 5.25,
      "delivery_days": 5
    },
    {
      "service": "PRIORITY_MAIL_EXPRESS",
      "price": 26.60,
      "delivery_days": 1
    }
  ]
}

Rate Limits

Rate limits are applied per API key, per minute. Exceeding your limit returns a 429 status. Current limits are returned in response headers.

// Response headers on every request
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1709913600

// When rate limited
HTTP/1.1 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "retry_after": 42
}

Error Handling

All errors return a consistent JSON structure with machine-readable error codes and human-readable messages.

// 400 Bad Request
{
  "error": "INVALID_ADDRESS",
  "message": "Street address is required",
  "field": "street"
}

// 401 Unauthorized
{
  "error": "INVALID_API_KEY",
  "message": "API key is missing or invalid"
}

// 403 Forbidden
{
  "error": "PLAN_LIMIT",
  "message": "Label creation requires Growth plan or higher"
}

SDKs & Libraries

Use our official SDKs for a faster integration.

Python PyPI

pip install usps-v3

Node.js npm

npm install usps-v3