Skip to main content
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: 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, 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:

​
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.