localis

Type a CPT/HCPCS code, a place, a service in plain words, or a whole claim line like 90837 LCSW 94110.

Try

4 min read Updated August 8, 2026

When a ZIP code can't tell you the truth

Nobody memorizes their Medicare payment locality code. They know their ZIP. So the rate lookup tool and API both accept a ZIP code and resolve it to a locality behind the scenes, against CMS's own ZIP-to-locality crosswalk. That sounds like a lookup-table problem — ZIP in, locality out — until you read the crosswalk closely enough to notice it isn't that simple. Some 5-digit ZIPs really do span more than one payment locality, and CMS's file says so explicitly. A resolver has to decide what to say when the honest answer is "it depends on the last four digits, which you didn't give me."

Two easy answers, both wrong

The tempting options are both a kind of lie. Pick one of the localities a flagged ZIP maps to and return it silently, and the response looks right for some addresses in that ZIP and wrong for others, with nothing to distinguish the two cases. Reject flagged ZIPs outright, and lookups break for real ZIPs that real Medicare claims get billed against every day, just because the resolver can't promise perfect precision.

Localis does neither. A flagged ZIP still resolves to a locality — the dominant one CMS's own crosswalk lists for it — but the result comes back explicitly marked as an approximate match, not an exact one, with a plain note that a more specific ZIP+4 would pin down the exact locality. The caller always gets an answer, and can always tell an approximate match from an exact one — the distinction that matters to someone using this rate to bill or appeal a claim.

Full ZIP+4 resolution needs a CMS override file we haven't ingested yet; a supplied ZIP+4 is recorded on the response but can't yet change which locality comes back. Saying "we recorded your ZIP+4 but can't act on it yet" is still more honest than silently treating the lookup as fully resolved.

Rates are historical, so ZIP resolution has to be too

The rate engine already supports "what would this code have paid in Q2 CY2024," because releases are immutable and versioned by quarter. ZIP resolution has to be equally historical: a locality boundary can move between crosswalk updates, so resolving today's ZIP-to-locality mapping against a two-year-old rate release would silently mix two different points in time. Instead, a historical lookup resolves the ZIP against whichever crosswalk was actually in effect for the requested quarter, so a historical rate and the ZIP resolution behind it always describe the same period.

Letting two inputs check each other instead of picking a winner

The API also accepts an explicit locality alongside a ZIP, for callers who already know their locality but want it cross-checked. When both agree, the ZIP acts as confirmation and the matched crosswalk record is cited as evidence. When they disagree, the request fails with a clear error rather than one input silently overriding the other — contradictory input is something to surface, not arbitrate quietly.

The interesting case is the third one: an ambiguous ZIP paired with an explicit locality that matches its dominant mapping. That's not treated as an error. An ambiguous ZIP's own warning says "provide more detail to disambiguate," and an explicit locality is exactly that — so the response says the explicit locality was used, rather than implying the dominant one was guessed at.

Parsing input honestly too

Even turning a string into a candidate ZIP resists the urge to guess past what's there. Localis accepts the reasonable real-world variants — five digits alone, five digits with a trailing ZIP+4 attached or supplied separately, with or without the dash, and a ZIP that lost a leading zero upstream. Anything else comes back as a clear "invalid ZIP" result, not a best-effort guess dressed up as a resolved locality.

The pattern

Every decision here is the same instinct applied at a different layer: resist false precision. Mark a lookup approximate instead of inventing a single right answer for a ZIP that doesn't have one. Resolve against the crosswalk that was actually in effect for a historical query instead of today's. Treat two inputs that disagree as a signal, not a tiebreak. A resolver that's occasionally allowed to say "I can't be exact here" is more trustworthy than one that's always confident and sometimes wrong — especially when the number it returns feeds into an actual Medicare claim.

Try a ZIP yourself on the locality lookup.

← All posts