# USPS API

> USPS provides package tracking, ZIP code details, and postage estimates as a workflow and API.

USPS returns package status and delivery details from a tracking number. Get zip code standardizes a US street address; Get city for zip finds city details from a ZIP Code. Estimate postage compares domestic retail options using ZIP Codes, weight, package shape, and mailing date.

- Page: https://fous.com/tools/usps
- Handle: `@usps`
- Category: [Logistics](https://fous.com/tools/category/logistics)
- Source website: https://usps.com
- Last verified: Sep 29, 2026

## Methods

### Estimate postage

Operation `estimate_postage`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Estimate domestic USPS Post Office retail postage by ZIP Codes, weight, shape, and mailing date. Shows available ordinary services or flat-rate packaging options; a zero-pound letter with no extra ounces is treated as a one-ounce letter. Media Mail is excluded because eligibility depends on contents. Delivery dates are estimates, and prices exclude optional paid extras.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `width_in` | number | no |  | Package width in inches, for example 6; defaults to a small box. |
| `height_in` | number | no |  | Package height in inches, for example 4; defaults to a small box. |
| `length_in` | number | no |  | Package length in inches, for example 8; defaults to a small box. |
| `ship_date` | string | no |  | Planned mailing date, for example 2026-10-01; defaults to today. |
| `weight_lb` | number | yes | `0` | Weight in pounds, for example 2; enter 0 for a letter under a pound. |
| `weight_oz` | number | no | `1` | Additional ounces beyond the whole pounds, for example 8. |
| `origin_zip` | string | yes | `"10001"` | Five-digit ZIP Code where the item is mailed, for example 10001. |
| `package_type` | string | no | `"letter"` | Mailpiece or USPS flat-rate packaging type, for example package. |
| `destination_zip` | string | yes | `"94105"` | Five-digit destination ZIP Code, for example 94105. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "origin_zip",
    "destination_zip",
    "weight_lb"
  ],
  "properties": {
    "width_in": {
      "type": "number",
      "default": 6,
      "description": "Package width in inches, for example 6; defaults to a small box.",
      "exclusiveMinimum": 0
    },
    "height_in": {
      "type": "number",
      "default": 4,
      "description": "Package height in inches, for example 4; defaults to a small box.",
      "exclusiveMinimum": 0
    },
    "length_in": {
      "type": "number",
      "default": 8,
      "description": "Package length in inches, for example 8; defaults to a small box.",
      "exclusiveMinimum": 0
    },
    "ship_date": {
      "type": "string",
      "format": "date",
      "description": "Planned mailing date, for example 2026-10-01; defaults to today."
    },
    "weight_lb": {
      "type": "number",
      "minimum": 0,
      "description": "Weight in pounds, for example 2; enter 0 for a letter under a pound.",
      "examples": [
        0,
        2
      ]
    },
    "weight_oz": {
      "type": "number",
      "default": 0,
      "minimum": 0,
      "description": "Additional ounces beyond the whole pounds, for example 8.",
      "examples": [
        1
      ]
    },
    "origin_zip": {
      "type": "string",
      "title": "From ZIP",
      "pattern": "^[0-9]{5}$",
      "description": "Five-digit ZIP Code where the item is mailed, for example 10001.",
      "examples": [
        "10001",
        "60601"
      ]
    },
    "package_type": {
      "enum": [
        "letter",
        "large_envelope",
        "package",
        "flat_rate_envelope",
        "flat_rate_box"
      ],
      "type": "string",
      "default": "package",
      "description": "Mailpiece or USPS flat-rate packaging type, for example package.",
      "examples": [
        "letter",
        "flat_rate_box"
      ]
    },
    "destination_zip": {
      "type": "string",
      "title": "To ZIP",
      "pattern": "^[0-9]{5}$",
      "description": "Five-digit destination ZIP Code, for example 94105.",
      "examples": [
        "94105",
        "90001"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "weight_lb": 0,
      "weight_oz": 1,
      "origin_zip": "10001",
      "package_type": "letter",
      "destination_zip": "94105"
    },
    {
      "weight_lb": 2,
      "origin_zip": "10001",
      "destination_zip": "94105"
    },
    {
      "weight_lb": 2,
      "origin_zip": "60601",
      "package_type": "flat_rate_box",
      "destination_zip": "90001"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `note` | string or null |  |  |
| `services` | array |  | Available retail postage options, cheapest first. |
| `services[].currency` | string | `"USD"` |  |
| `services[].page_link` | string | `"https://postcalc.usps.com/Calculator/ExtraServices?country=0&ccode=US&oz=10001&omil=False&dz=94105&dmil=False&retail=Fa` |  |
| `services[].retail_price` | number | `0.82` |  |
| `services[].service_name` | string | `"First-Class Mail Stamped Letter"` |  |
| `services[].included_extras` | array |  |  |
| `services[].expected_delivery_date` | string or null | `"2026-10-03"` |  |
| `services[].estimated_delivery_time` | string or null | `"Sat, Oct 3"` |  |

**Example input**

```json
{
  "weight_lb": 0,
  "weight_oz": 1,
  "origin_zip": "10001",
  "package_type": "letter",
  "destination_zip": "94105"
}
```

**Example output**

```json
{
  "note": null,
  "services": [
    {
      "currency": "USD",
      "page_link": "https://postcalc.usps.com/Calculator/ExtraServices?country=0&ccode=US&oz=10001&omil=False&dz=94105&dmil=False&retail=False&mdt=9/28/2026&mdz=8:00 AM&m=1&hscode=False&p=0&o=1&rect=True&l=0&h=0&w=0&g=0&…",
      "retail_price": 0.82,
      "service_name": "First-Class Mail Stamped Letter",
      "included_extras": [],
      "expected_delivery_date": "2026-10-03",
      "estimated_delivery_time": "Sat, Oct 3"
    },
    {
      "currency": "USD",
      "page_link": "https://postcalc.usps.com/Calculator/ExtraServices?country=0&ccode=US&oz=10001&omil=False&dz=94105&dmil=False&retail=False&mdt=9/28/2026&mdz=8:00 AM&m=1&hscode=False&p=0&o=1&rect=True&l=0&h=0&w=0&g=0&…",
      "retail_price": 16.95,
      "service_name": "Priority Mail",
      "included_extras": [
        "USPS Tracking",
        "Insurance up to $100"
      ],
      "expected_delivery_date": "2026-10-01",
      "estimated_delivery_time": "Thu, Oct 1"
    },
    {
      "currency": "USD",
      "page_link": "https://postcalc.usps.com/Calculator/ExtraServices?country=0&ccode=US&oz=10001&omil=False&dz=94105&dmil=False&retail=False&mdt=9/28/2026&mdz=8:00 AM&m=1&hscode=False&p=0&o=1&rect=True&l=0&h=0&w=0&g=0&…",
      "retail_price": 53.35,
      "service_name": "Priority Mail Express",
      "included_extras": [
        "USPS Tracking",
        "Insurance up to $100"
      ],
      "expected_delivery_date": "2026-09-29",
      "estimated_delivery_time": "Tue, Sep 29 by 6:00 PM"
    }
  ]
}
```

### Get city for zip

Operation `get_city_for_zip`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find the USPS recommended city and state, other recognized city names, names to avoid, and ZIP type for a five-digit US ZIP Code. ZIP+4 is reduced to its first five digits.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `zip_code` | string | yes | `"90210-1234"` | Five-digit ZIP Code or ZIP+4, for example 10001 or 10001-1234. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "zip_code"
  ],
  "properties": {
    "zip_code": {
      "type": "string",
      "description": "Five-digit ZIP Code or ZIP+4, for example 10001 or 10001-1234.",
      "examples": [
        "90210-1234",
        "10001",
        "22102"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "zip_code": "90210-1234"
    },
    {
      "zip_code": "10001"
    },
    {
      "zip_code": "22102"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `page_url` | string | `"https://tools.usps.com/zip-code-lookup.htm?citybyzipcode"` | USPS Cities by ZIP Code page. |
| `zip_code` | string | `"90210"` | The five-digit ZIP Code. |
| `zip_type` | string or null | `"Standard"` | ZIP classification when provided, such as PO Box only or Military. |
| `state_code` | string | `"CA"` | Two-letter state or territory abbreviation. |
| `state_name` | string | `"California"` | Full state or territory name. |
| `cities_to_avoid` | array |  | City names USPS says to avoid for this ZIP Code. |
| `recommended_city` | string | `"BEVERLY HILLS"` | USPS recommended city name. |
| `other_accepted_cities` | array |  | Other city names USPS recognizes for addresses in this ZIP Code. |

**Example input**

```json
{
  "zip_code": "90210-1234"
}
```

**Example output**

```json
{
  "page_url": "https://tools.usps.com/zip-code-lookup.htm?citybyzipcode",
  "zip_code": "90210",
  "zip_type": "Standard",
  "state_code": "CA",
  "state_name": "California",
  "cities_to_avoid": [],
  "recommended_city": "BEVERLY HILLS",
  "other_accepted_cities": []
}
```

### Get zip code

Operation `get_zip_code`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Standardize a US street address with USPS and find its ZIP+4. When several addresses match, the main address is the first result and all choices appear in matches. A ZIP Code result does not confirm who lives at an address.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `city` | string | yes | `"Washington"` | City name, such as Washington. |
| `state` | string | yes | `"DC"` | State name or two-letter code, such as District of Columbia or DC. |
| `zip_code` | string | no | `"10118"` | ZIP Code if known, such as 20500. |
| `street_address` | string | yes | `"1600 Pennsylvania Ave NW"` | Street number and name, such as 1600 Pennsylvania Ave NW. |
| `apartment_or_suite` | string | no | `"Ste 4750"` | Unit or suite, such as Apt 4B. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "street_address",
    "city",
    "state"
  ],
  "properties": {
    "city": {
      "type": "string",
      "description": "City name, such as Washington.",
      "examples": [
        "Washington",
        "New York"
      ]
    },
    "state": {
      "type": "string",
      "description": "State name or two-letter code, such as District of Columbia or DC.",
      "examples": [
        "DC",
        "New York",
        "NY"
      ]
    },
    "zip_code": {
      "type": "string",
      "default": "",
      "description": "ZIP Code if known, such as 20500.",
      "examples": [
        "10118"
      ]
    },
    "street_address": {
      "type": "string",
      "description": "Street number and name, such as 1600 Pennsylvania Ave NW.",
      "examples": [
        "1600 Pennsylvania Ave NW",
        "350 5th Ave",
        "99999 Madeup Street"
      ]
    },
    "apartment_or_suite": {
      "type": "string",
      "default": "",
      "description": "Unit or suite, such as Apt 4B.",
      "examples": [
        "Ste 4750"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "city": "Washington",
      "state": "DC",
      "street_address": "1600 Pennsylvania Ave NW"
    },
    {
      "city": "New York",
      "state": "New York",
      "street_address": "350 5th Ave"
    },
    {
      "city": "Washington",
      "state": "DC",
      "street_address": "99999 Madeup Street"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `city` | string or null | `"WASHINGTON"` | USPS-formatted city. |
| `note` | string or null | `"Check the street number, street name, city, state, ZIP Code, and apartment or suite if applicable."` | What to check when no address is recognized. |
| `state` | string or null | `"DC"` | Two-letter USPS state abbreviation. |
| `county` | string or null | `"DISTRICT OF COLUMBIA"` | USPS county name. |
| `matches` | array |  | All USPS address choices when multiple results are found; otherwise empty. |
| `matches[].city` | string or null | `"NEW YORK"` | USPS-formatted city. |
| `matches[].state` | string or null | `"NY"` | Two-letter USPS state abbreviation. |
| `matches[].county` | string or null | `"NEW YORK"` | USPS county name. |
| `matches[].page_url` | string | `"https://tools.usps.com/zip-code-lookup.htm?byaddress"` | USPS lookup page for this address. |
| `matches[].zip_code` | string or null | `"10118"` | Five-digit ZIP Code. |
| `matches[].zip_plus_4` | string or null | `"10118-0110"` | Nine-digit ZIP+4 in five-plus-four format. |
| `matches[].street_line` | string or null | `"350 5TH AVE"` | USPS-formatted street address, including unit when present. |
| `matches[].carrier_route` | string or null | `"C082"` | USPS mail carrier route. |
| `matches[].delivery_point` | string or null | `"99"` | USPS delivery point code. |
| `page_url` | string | `"https://tools.usps.com/zip-code-lookup.htm?byaddress"` | USPS lookup page for this address. |
| `zip_code` | string or null | `"20500"` | Five-digit ZIP Code. |
| `recognized` | string | `"yes"` | Whether USPS returned an address match. |
| `zip_plus_4` | string or null | `"20500-0005"` | Nine-digit ZIP+4 in five-plus-four format. |
| `street_line` | string or null | `"1600 PENNSYLVANIA AVE NW"` | USPS-formatted street address, including unit when present. |
| `carrier_route` | string or null | `"C000"` | USPS mail carrier route. |
| `delivery_point` | string or null | `"00"` | USPS delivery point code. |

**Example input**

```json
{
  "city": "Washington",
  "state": "DC",
  "street_address": "1600 Pennsylvania Ave NW"
}
```

**Example output**

```json
{
  "city": "WASHINGTON",
  "note": null,
  "state": "DC",
  "county": "DISTRICT OF COLUMBIA",
  "matches": [],
  "page_url": "https://tools.usps.com/zip-code-lookup.htm?byaddress",
  "zip_code": "20500",
  "recognized": "yes",
  "zip_plus_4": "20500-0005",
  "street_line": "1600 PENNSYLVANIA AVE NW",
  "carrier_route": "C000",
  "delivery_point": "00"
}
```

### Track package

Operation `track_package`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Track a USPS package or letter by its tracking number. Returns the latest status, delivery details, and available tracking history; unavailable or ambiguous numbers may need additional details on USPS.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `tracking_number` | string | yes | `"9489 0178 9820 3036 9522 01"` | Tracking number on the receipt or label, such as 9400 1000 0000 0000 0000 00 or EC123456789US. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "tracking_number"
  ],
  "properties": {
    "tracking_number": {
      "type": "string",
      "description": "Tracking number on the receipt or label, such as 9400 1000 0000 0000 0000 00 or EC123456789US.",
      "examples": [
        "9489 0178 9820 3036 9522 01",
        "9489017898203036952201"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "tracking_number": "9489 0178 9820 3036 9522 01"
    },
    {
      "tracking_number": "9489017898203036952201"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `events` | array |  |  |
| `events[].event` | string | `"Delivered, Left with Individual"` |  |
| `events[].location` | string or null | `"LAS VEGAS, NV 89119"` |  |
| `events[].date_time` | string or null | `"2026-01-31T14:21:00-08:00"` | Local date and time of the event, ISO 8601 with UTC offset when the location can be resolved. |
| `status` | string | `"Delivered, Left with Individual"` |  |
| `delivered_at` | string or null | `"2026-01-31T14:21:00-08:00"` |  |
| `mail_service` | string or null | `"First-Class Mail®"` |  |
| `last_location` | string or null | `"LAS VEGAS, NV 89119"` |  |
| `tracking_link` | string | `"https://tools.usps.com/go/TrackConfirmAction?tLabels=9489017898203036952201"` |  |
| `last_event_time` | string or null | `"2026-01-31T14:21:00-08:00"` |  |
| `tracking_number` | string | `"9489017898203036952201"` |  |
| `expected_delivery_date` | string or null |  |  |
| `expected_delivery_time_window` | string or null |  |  |

**Example input**

```json
{
  "tracking_number": "9489 0178 9820 3036 9522 01"
}
```

**Example output**

```json
{
  "events": [
    {
      "event": "Delivered, Left with Individual",
      "location": "LAS VEGAS, NV 89119",
      "date_time": "2026-01-31T14:21:00-08:00"
    },
    {
      "event": "Arrived at USPS Facility",
      "location": "LAS VEGAS NV DISTRIBUTION CENTER",
      "date_time": "2026-01-30T08:29:00-08:00"
    },
    {
      "event": "Arrived at USPS Facility",
      "location": "RENO NV DISTRIBUTION CENTER",
      "date_time": "2026-01-29T09:30:00-08:00"
    }
  ],
  "status": "Delivered, Left with Individual",
  "delivered_at": "2026-01-31T14:21:00-08:00",
  "mail_service": "First-Class Mail®",
  "last_location": "LAS VEGAS, NV 89119",
  "tracking_link": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9489017898203036952201",
  "last_event_time": "2026-01-31T14:21:00-08:00",
  "tracking_number": "9489017898203036952201",
  "expected_delivery_date": null,
  "expected_delivery_time_window": null
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@usps",
  "visibility": "public",
  "operation": "estimate_postage",
  "version": 1,
  "input": {
    "weight_lb": 0,
    "weight_oz": 1,
    "origin_zip": "10001",
    "package_type": "letter",
    "destination_zip": "94105"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@usps\",\n  \"visibility\": \"public\",\n  \"operation\": \"estimate_postage\",\n  \"version\": 1,\n  \"input\": {\n    \"weight_lb\": 0,\n    \"weight_oz\": 1,\n    \"origin_zip\": \"10001\",\n    \"package_type\": \"letter\",\n    \"destination_zip\": \"94105\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@usps",
  "visibility": "public",
  "operation": "estimate_postage",
  "version": 1,
  "input": {
    "weight_lb": 0,
    "weight_oz": 1,
    "origin_zip": "10001",
    "package_type": "letter",
    "destination_zip": "94105"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/usps`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `estimate_postage`: Estimate postage. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_city_for_zip`: Get city for zip. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_zip_code`: Get zip code. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `track_package`: Track package. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-usps https://api.fous.com/mcp/tools/usps --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Check package status and delivery details using a tracking number.
- Standardize street addresses and find ZIP+4 codes.
- Find recommended and accepted city names for a ZIP Code.
- Compare domestic retail postage options by price and service.
- Estimate postage for a planned mailing date and package size.

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this USPS tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a USPS account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from usps.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What is the latest status of a package?

Track package returns the latest status, delivery details, and available tracking history for a tracking number.

### What ZIP+4 matches a US street address?

Get zip code standardizes the address and returns a ZIP+4; when several addresses match, it also returns the choices.

### What city and state does a ZIP Code use?

Get city for zip returns the USPS recommended city and state, other accepted city names, names to avoid, and ZIP type.

## Related

- [All Logistics tools](https://fous.com/tools/category/logistics)