> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perfectreferral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Address Normalization & Geocoding

From street abbreviations to formatting errors, addresses are messy. Because of
these issues, superficially distinct addresses limit our ability to use evidence
that a practitioner actually practices at a location, as it is erroneously spread
across the variants. To address this, we normalize addresses to help silence some of
the noise and improve our estimations. Every address in the API is reformatted to
United States Postal Service (USPS) standards before you receive it. The raw text
from the underlying source is rewritten into one consistent form, so the same
location is spelled the same way no matter which source it came from.

The same building otherwise arrives spelled many ways: `123 Park Center Dr., Suite 400`,
`123 PARK CTR DRIVE STE 400`, `123 Park Ctr Dr #400`. Normalization collapses these
to a single form.

## The standard: USPS Publication 28

Addresses are normalized to **USPS Publication 28, *Postal Addressing Standards*** —
the standard the Postal Service uses to define a mailable address. In practice:

| Rule                       | Effect                           | Example                         |
| :------------------------- | :------------------------------- | :------------------------------ |
| Upper-case & punctuation   | Capitalized, punctuation removed | `Park Ctr Dr.` → `PARK CTR DR`  |
| Street suffixes (App. C1)  | Standardized abbreviation        | `AVENUE`, `AV`, `AVNUE` → `AVE` |
| Unit designators (App. C2) | Standardized abbreviation        | `SUITE` → `STE`, `FLOOR` → `FL` |
| Directionals               | Compass words abbreviated        | `NORTH MAIN` → `N MAIN`         |
| ZIP                        | Reduced to five digits           | `75081-1234` → `75081`          |

We use the full USPS C1/C2 tables, so any spelling a source uses (`DRV`,
`BOULEVARD`, `AVNUE`) lands on the standard form.

## How it works

The street line is parsed by [libpostal](https://github.com/openvenues/libpostal),
an open-source address parser, into components - house number, street, unit, PO box -
which are then rewritten per Pub 28 and reassembled. Only the street line is parsed;
**city, state, and ZIP come straight from the source's own fields** and are trusted
as written (re-parsing them would mistake a suite for a ZIP, or shorten
`LONG ISLAND CITY` to `CITY`).

The fields we include in API responses:

| Field           | Contents                                                 |
| :-------------- | :------------------------------------------------------- |
| `line1`         | House number + street, or the PO box (`943 PINE LOG RD`) |
| `line2`         | Secondary unit, if any (`STE 400`)                       |
| `city`, `state` | As the source states them, upper-cased                   |
| `postal_code`   | Five-digit ZIP                                           |

## Geocoding annotations

To ensure consistent and accurate location data, our geocoding methodology uses a
prioritized, three-tiered hierarchy. We first utilize any coordinates native to the
dataset, such as those from the CMS National Provider Directory. If that source is
unavailable, we fall back to a self-hosted Nominatim instance, which leverages
OpenStreetMap and U.S. Census TIGER/Line data. Finally, for any addresses not
resolved by the first two sources, we use Geocodio as a commercial service, which
operates its own geocoding engine assembled from a large number of public and
government datasets.

Positional accuracy is not uniform across the three tiers, and the precision of any
given coordinate depends on which tier produced it. Rooftop matches, where the
coordinate corresponds to the actual structure, cover roughly 70 percent of a
typical evenly distributed U.S. address sample, with about 20 percent resolving to
street-range interpolation, which estimates a position along a street segment rather
than locating the building. The remainder fall back to coarser results such as city
or ZIP centroids. Suite and floor are not resolved: a provider in a multi-tenant
medical office building geocodes to the building, not the practice.

## Limitations

Normalization is a best-effort process running on messy real-world data:

* **We reformat, we don't correct.** A typo in the source is a typo in the output.
* **Unusual addresses can be mislabeled.** Grid-style numbers, Puerto Rico forms, or
  run-together tokens can occasionally cause a token in `line1` to be misplaced.
* **`city` is passed through untouched**, not standardized (no `SAINT`/`ST` folding,
  no abbreviation expansion).
* **Not validated against USPS's database.** "USPS-conformant" means conformant to
  the *text* of Pub 28, not checked against the USPS Address Management System. We
  cannot confirm an address is deliverable, or that a city and ZIP are consistent.