> ## Documentation Index
> Fetch the complete documentation index at: https://paperplane-justin-winter-s-projects.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Addresses

> USPS verification, autocomplete, and how paperplane handles corrected addresses.

## The authoritative source is USPS

`POST /v1/orders` verifies both the recipient and the sender against USPS. If standardization changes the address (e.g. `San Francisco` → `SAN FRANCISCO`, or a casing/abbreviation fix), the response includes the corrected version you'll actually mail to:

```json theme={null}
{
  "status": "ok",
  "order": { "...": "..." },
  "corrected_to": {
    "name": "Ada Lovelace",
    "line1": "1 ANALYSIS WAY",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94107"
  }
}
```

<Note>
  The order's `to` field stays as addressed. `corrected_to` is what USPS will actually deliver to. Quote it back only if you need to display the canonical form.
</Note>

## Autocomplete (typeahead)

`GET /v1/address/autocomplete?q=...` returns candidate addresses as the user types:

```json theme={null}
{
  "enabled": true,
  "suggestions": [
    { "line1": "1 Analysis Way", "city": "San Francisco", "state": "CA", "zip": "94107", "label": "..." }
  ]
}
```

`enabled` is `false` (with an empty `suggestions` array) when no geocoding
provider is configured on this deployment — there is no `status` field on
this endpoint.

## Reverse geocode

`GET /v1/address/reverse?lat=...&lon=...` returns the address nearest a lat/lon — useful for map clicks. Note the parameter is `lon`, not `lng`:

```bash theme={null}
curl "https://sendpaperplane.com/v1/address/reverse?lat=37.7749&lon=-122.4194"
```

Response shape mirrors autocomplete: `{ "enabled": true, "address": {...} }`, or `{ "enabled": false, "address": null }` when unconfigured.

<Note>
  Autocomplete and reverse geocoding are **convenience only**. USPS verification on order creation is the authoritative check. Don't ship mail off the typeahead without the order's verification pass.
</Note>

## What failure looks like

An unverifiable address fails the order with an address error in the envelope (a `code` + `next` with the USPS-corrected candidate when available), rather than mailing to a guess.