← Docs / API Reference

API Reference

41 routes. Every endpoint documented with parameters, request/response examples, and copy-paste code. Base URL: https://api.revaddress.com

OpenAPI 3.1 spec Get a free API key →

Address validation, city/state lookup, and rate shopping work free — no API key needed. Just hit the endpoint.

Authentication

Free Tier

No API key required. IP-rate-limited: 30 req/10s. Address validation, rates, locations, service standards.

Protected

X-API-Key: rv_live_...
Labels, tracking, pickup, batch validation.

Rate Limits

Starter 120/min · Growth 300/min · Pro 600/min. Headers: X-RateLimit-Limit, -Remaining, -Reset.

Try it live

Hit the real USPS API right now. No API key, no signup — free tier, live data.

Street Address

City

State

ZIP

Response

← Enter an address and click Validate

Quick Start Examples

The four most common first requests. Hit the live API immediately.

POST /api/address/validate

Address validation — free tier, no key needed

FREE

curl -s "https://api.revaddress.com/api/address/validate" \
  -H "Content-Type: application/json" \
  -d '{"streetAddress":"228 Park Ave S PMB 101842","city":"New York","state":"NY","ZIPCode":"10003"}'

import requests

resp = requests.post(
    "https://api.revaddress.com/api/address/validate",
    json={
        "streetAddress": "228 Park Ave S PMB 101842",
        "city": "New York",
        "state": "NY",
        "ZIPCode": "10003"
    }
)
data = resp.json()
print(data["address"]["ZIPPlus4"])  # 1502

const resp = await fetch("https://api.revaddress.com/api/address/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    streetAddress: "228 Park Ave S PMB 101842",
    city: "New York",
    state: "NY",
    ZIPCode: "10003"
  })
});
const { address, additionalInfo } = await resp.json();
console.log(address.ZIPPlus4);       // "1502"
console.log(additionalInfo.DPVConfirmation); // "Y"

POST /api/rates

Rate shopping across all USPS mail classes

FREE

curl -s "https://api.revaddress.com/api/rates" \
  -H "Content-Type: application/json" \
  -d '{"originZIPCode":"10003","destinationZIPCode":"90210","weight":2.5,"length":12,"width":9,"height":2}'

import requests

resp = requests.post(
    "https://api.revaddress.com/api/rates",
    json={
        "originZIPCode": "10003",
        "destinationZIPCode": "90210",
        "weight": 2.5,
        "length": 12,
        "width": 9,
        "height": 2
    }
)
data = resp.json()
for opt in data["rates"]["rateOptions"]:
    print(f"{opt['mailClass']}: ${opt['totalBasePrice']:.2f} (zone {opt['zone']})")

const resp = await fetch("https://api.revaddress.com/api/rates", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    originZIPCode: "10003",
    destinationZIPCode: "90210",
    weight: 2.5,
    length: 12, width: 9, height: 2
  })
});
const { rates, serviceStandards } = await resp.json();
for (const opt of rates.rateOptions) {
  console.log(`${opt.mailClass}: $${opt.totalBasePrice}`);
}

POST /api/batch/validate

Up to 50 addresses in one request

Growth+

curl -s "https://api.revaddress.com/api/batch/validate" \
  -H "X-API-Key: rv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"addresses":[{"streetAddress":"228 Park Ave S","city":"New York","state":"NY","ZIPCode":"10003"},{"streetAddress":"1600 Pennsylvania Ave NW","city":"Washington","state":"DC","ZIPCode":"20500"}]}'

import requests

addresses = [
    {"streetAddress": "228 Park Ave S", "city": "New York", "state": "NY", "ZIPCode": "10003"},
    {"streetAddress": "1600 Pennsylvania Ave NW", "city": "Washington", "state": "DC", "ZIPCode": "20500"},
]

resp = requests.post(
    "https://api.revaddress.com/api/batch/validate",
    headers={"X-API-Key": "rv_live_your_key_here"},
    json={"addresses": addresses}
)
data = resp.json()
print(f"Validated: {data['successful']}/{data['total']}")
print(f"Cache hits: {data['usage']['cached_hits']}")

const resp = await fetch("https://api.revaddress.com/api/batch/validate", {
  method: "POST",
  headers: {
    "X-API-Key": "rv_live_your_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    addresses: [
      { streetAddress: "228 Park Ave S", city: "New York", state: "NY", ZIPCode: "10003" },
      { streetAddress: "1600 Pennsylvania Ave NW", city: "Washington", state: "DC" }
    ]
  })
});
const { total, successful, results, usage } = await resp.json();
console.log(`Validated ${successful}/${total}, ${usage.cached_hits} from cache`);

GET /api/tracking/:number

Full scan history with status categories

Starter+

curl -s "https://api.revaddress.com/api/tracking/9400111899223456789012" \
  -H "X-API-Key: rv_live_your_key_here"

import requests

resp = requests.get(
    "https://api.revaddress.com/api/tracking/9400111899223456789012",
    headers={"X-API-Key": "rv_live_your_key_here"}
)
data = resp.json()
print(data["statusCategory"])  # "Delivered"
for event in data["trackingEvents"]:
    print(event["eventTimestamp"], event["eventType"])

const resp = await fetch(
  "https://api.revaddress.com/api/tracking/9400111899223456789012",
  { headers: { "X-API-Key": "rv_live_your_key_here" } }
);
const { statusCategory, trackingEvents } = await resp.json();
console.log(statusCategory); // "Delivered"

Addresses

Free Tier

US address validation and ZIP lookup. Free tier — no API key needed.

Validate and standardize a US address using USPS CASS-certified data. Returns ZIP+4, DPV confirmation, residential/business classification, and vacancy status. Results are cached in KV for 24 hours.

Parameters

Name	In	Required	Example
`streetAddress`	query	required	228 Park Ave S PMB 101842
`secondaryAddress`	query	optional	Suite 100
`city`	query	optional	New York
`state`	query	optional	NY
`ZIPCode`	query	optional	10003

Response

{
  "address": {
    "streetAddress": "228 PARK AVE S PMB 101842",
    "city": "NEW YORK",
    "state": "NY",
    "ZIPCode": "10003",
    "ZIPPlus4": "1502"
  },
  "additionalInfo": {
    "deliveryPoint": "42",
    "DPVConfirmation": "Y",
    "business": "Y",
    "vacant": "N"
  },
  "matches": [{ "code": "31", "text": "Single Response - exact match" }],
  "cached": false
}

Returns city and state for a 5-digit ZIP code.

Parameters

Name	In	Required	Example
`ZIPCode`	query	required	10003

Response

{
  "zip5": "10003",
  "city": "NEW YORK",
  "state": "NY"
}

Rates

Free Tier

Domestic and international shipping rate quotes. Free tier.

Tracking

USPS package tracking by tracking number.

Returns tracking status and full scan event history from USPS Tracking v3.2. Events are stored in D1 for analytics. Supports all USPS tracking number formats. expand=SUMMARY returns status only; DETAIL (default) includes all scan events.

Parameters

Name	In	Required	Example
`trackingNumber`	path	required	9400111899223456789012
`expand` SUMMARY or DETAIL (default)	query	optional	DETAIL

Response

{
  "trackingNumber": "9400111899223456789012",
  "statusCategory": "Delivered",
  "statusSummary": "Your item was delivered at 2:22 pm on March 8, 2026.",
  "expectedDeliveryDate": "2026-03-08",
  "trackingEvents": [
    {
      "eventType": "DELIVERED",
      "eventCode": "01",
      "eventCity": "WASHINGTON",
      "eventState": "DC",
      "eventZIP": "20500",
      "eventTimestamp": "2026-03-08T14:22:00Z"
    },
    {
      "eventType": "OUT_FOR_DELIVERY",
      "eventCode": "OF",
      "eventCity": "WASHINGTON",
      "eventState": "DC",
      "eventZIP": "20500",
      "eventTimestamp": "2026-03-08T08:15:00Z"
    }
  ]
}

Labels

Create, download, list, and void USPS shipping labels.

Creates a USPS shipping label. In workflow mode (default), returns a workflowId — send POST /api/workflows/{id}/approve to authorize the charge. In direct mode, creates the label synchronously and returns the PDF URL. Use ?tem=true for watermarked test labels (no charge). Supports idempotencyKey to prevent duplicate charges on retries.

Parameters

Name	In	Required	Example
`tem` Use TEM (test labels, no charge)	query	optional	false

Request Body

{
  "fromAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "streetAddress": "228 Park Ave S PMB 101842",
    "city": "New York",
    "state": "NY",
    "ZIPCode": "10003"
  },
  "toAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "streetAddress": "1600 Pennsylvania Ave NW",
    "city": "Washington",
    "state": "DC",
    "ZIPCode": "20500"
  },
  "mailClass": "PRIORITY_MAIL",
  "weight": 2.5,
  "length": 12,
  "width": 9,
  "height": 2,
  "idempotencyKey": "order-12345-label-1"
}

Response

// Workflow mode — 202 Accepted
{
  "workflowId": "wf_abc123def456",
  "status": "pending_approval",
  "message": "Workflow created. Send POST /api/workflows/{id}/approve to authorize charge."
}

// Direct mode — 201 Created
{
  "labelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "9400111899223456789012",
  "postage": 8.55,
  "zone": "5",
  "commitment": { "name": "2 Days", "scheduleDeliveryDate": "2026-03-12" },
  "labelUrl": "/api/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download",
  "environment": "production"
}

Returns your most recent labels. Scoped to your merchant ID. Use ?limit=N to control page size (1–100, default 20).

Parameters

Name	In	Required	Example
`limit` 1–100, default 20	query	optional	20

Response

{
  "labels": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tracking_number": "9400111899223456789012",
      "mail_class": "PRIORITY_MAIL",
      "postage": 8.55,
      "status": "delivered",
      "commitment": "2 Days",
      "created_at": 1741234567890
    }
  ]
}

Returns the label PDF from R2 storage. Response is application/pdf with Content-Disposition: attachment. Labels are scoped to your merchant ID.

Parameters

Name	In	Required	Example
`labelId`	path	required	a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

// Returns binary PDF — application/pdf

Voids a label and requests a USPS postage refund. Cannot void delivered or already-voided labels. USPS void request is fire-and-forget — the D1 record is always updated regardless of USPS response.

Parameters

Name	In	Required	Example
`labelId`	path	required	a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

{
  "labelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "9400111899223456789012",
  "status": "voided",
  "refundAmount": 8.55,
  "voidedAt": "2026-03-10T12:00:00.000Z"
}

Workflows

Durable label creation workflows with charge-approval gate.

Returns current Cloudflare Workflow status and step progress for a label creation workflow.

Parameters

Name	In	Required	Example
`workflowId`	path	required	wf_abc123def456

Response

{
  "workflowId": "wf_abc123def456",
  "status": "running",
  "output": null
}

Sends the charge-approved event to an awaiting label workflow. Unblocks step 3 (waitForEvent) and allows label creation to proceed.

Parameters

Name	In	Required	Example
`workflowId`	path	required	wf_abc123def456

Request Body

{ "approved": true }

Response

{
  "workflowId": "wf_abc123def456",
  "event": "charge-approved",
  "payload": { "approved": true }
}

Pickup

Schedule and manage free USPS carrier pickups.

Locations & Standards

Free Tier

USPS drop-off locations and delivery time standards. Free tier.

Find USPS Post Offices, collection boxes, and retail locations near a ZIP code. Results cached for 24 hours.

Parameters

Name	In	Required	Example
`destinationZIPCode`	query	required	10003
`mailClass` Default: PARCEL_SELECT	query	optional	PARCEL_SELECT
`originZIPCode`	query	optional	10001
`weight`	query	optional	2.5

Response

{
  "dropOffLocations": [
    {
      "locationName": "JAMES A. FARLEY BLDG",
      "streetAddress": "421 8TH AVE",
      "city": "NEW YORK",
      "state": "NY",
      "zipCode": "10001",
      "locationType": "POST_OFFICE"
    }
  ],
  "cached": false
}

Returns USPS delivery time estimates between two ZIP codes by mail class. Results cached for 24 hours (standards change quarterly).

Parameters

Name	In	Required	Example
`originZIPCode`	query	required	10003
`destinationZIPCode`	query	required	90210
`mailClass`	query	optional	PRIORITY_MAIL

Response

{
  "estimates": [
    { "mailClass": "PRIORITY_MAIL", "days": 2, "scheduleDeliveryDate": "2026-03-12" },
    { "mailClass": "USPS_GROUND_ADVANTAGE", "days": 5, "scheduleDeliveryDate": "2026-03-15" }
  ],
  "cached": false
}

Returns available USPS shipping products for a given origin/destination pair.

Parameters

Name	In	Required	Example
`originZIPCode`	query	required	10003
`destinationZIPCode`	query	required	90210
`mailClass`	query	optional	PRIORITY_MAIL
`weight`	query	optional	1
`priceType`	query	optional	RETAIL

Response

{
  "shipmentOptions": [
    {
      "mailClass": "PRIORITY_MAIL",
      "serviceId": "PM",
      "commitment": "2 Days",
      "priceType": "RETAIL"
    }
  ]
}

BYOK

Bring your own USPS Developer Portal credentials. AES-GCM encrypted at rest.

Account

Self-service usage and key management. Scoped to your API key.

Returns API call breakdown by endpoint for the authenticated merchant. Scoped to your API key. Optionally filter by month (YYYY-MM).

Parameters

Name	In	Required	Example
`month` YYYY-MM format	query	optional	2026-03

Response

{
  "usage": [
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/address/validate", "call_count": 892 },
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/tracking/:number", "call_count": 231 },
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/rates", "call_count": 124 }
  ],
  "filters": { "merchant_id": "stripe_cus_abc123", "month": "2026-03" }
}

Revoke an API key that belongs to your merchant account. Only keys that belong to your own merchant ID can be revoked.

Parameters

Name	In	Required	Example
`keyHash`	path	required	a1b2c3d4e5f6...

Response

{ "key_hash": "a1b2c3d4e5f6...", "revoked": true }

Error Reference

All errors return a consistent JSON shape with machine-readable codes.

{
  "error": "usps_auth_failed",
  "message": "OAuth token expired or invalid",
  "status": 401,
  "code": "AUTH_EXPIRED",
  "retryable": true
}

Error Code	HTTP Status	Retryable	Action
api_key_required	401	—	Add X-API-Key header
invalid_api_key	401	—	Check key prefix (rv_live_ or rv_test_)
api_key_revoked	401	—	Generate a new key
rate_limit_exceeded	429	Yes	Check retryAfter in response, back off
monthly_limit_exceeded	429	Next month	Upgrade plan at /pricing
free_tier_rate_limit	429	Yes	Slow down or get a free API key
tier_required	403	—	Upgrade plan (batch requires Growth+)
usps_validation_error	422	No	Fix input address data
usps_auth_failed	401	Yes	Token auto-refreshes — retry once
payment_token_unavailable	503	Yes	Retry after a few seconds
batch_too_large	400	No	Split into batches of ≤50

SDKs

Python v1.0.0

pip install usps-v3

PyPI GitHub Tutorial

Node.js v1.0.0

npm install usps-v3

npm GitHub Tutorial

PHP v1.0.0

composer require revaddress/usps-v3-php

Packagist GitHub Magento Guide