localis
API key

Describe a service in plain words, or type a CPT/HCPCS code.

Geography API

API v1

Resolve ZIP codes through versioned CMS crosswalks and browse Medicare payment localities.

Single ZIP → locality lookup

Resolve a ZIP code to its Medicare payment locality on its own, without also pricing a code — useful for populating a locality picker or validating an address book against the crosswalk. Accepts a bare 5-digit ZIP, a "ZIP+4" (90210-1234 or 902101234), or a separate plus4 parameter.

This differs from passing zip= to the rate endpoints: a rate lookup must reject an ambiguous ZIP outright, because silently picking a locality risks pricing at the wrong rate. This endpoint instead returns the dominant locality with ambiguous: true and a note — a useful answer on its own, honestly labeled.

GET /v1/zip/{zip}
plus4
string
The ZIP+4 extension, if not already embedded in the path.
year, quarter, as_of
Resolve against a historical crosswalk release instead of the most recently published one.
request 
curl https://localishealth.com/v1/zip/90210 \
  -H "Authorization: Bearer sk_live_…"
response — 200 
{
  "status": "exact",
  "input_zip": "90210",
  "zip5": "90210",
  "plus4": null,
  "mac_code": "01182",
  "locality_code": "18",
  "locality": { "id": 1, "name": "Los Angeles, CA", "state": "CA" },
  "ambiguous": false,
  "crosswalk_release": { "year": 2026, "quarter": "A" },
  "reason": null,
  "citations": { "sources": { "zip_locality": { "file": "ZIP5_2026.csv", "row": 4, … } } }
}

status is one of exact, ambiguous, not_found, or invalid_zip. Only not_found and invalid_zip return a non-200 status (404). Historical selectors also echo requested_period; substituted or reconstructed crosswalks include notes and data_quality.

Bulk ZIP → locality lookup

Resolve up to 500 ZIPs in one request against a shared crosswalk release. Every entry resolves independently and always comes back in results — an unresolvable ZIP doesn't fail the batch, it comes back with its own status and reason.

POST /v1/zip/bulk
zips
array — required
Up to 500 entries. Each is a string ("90210", "90210-1234") or an object { zip, plus4? }.
year, quarter, as_of
Resolve every ZIP in the batch against a historical crosswalk release instead of the most recently published one.
request 
curl -X POST https://localishealth.com/v1/zip/bulk \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"zips": ["90210", "35801", {"zip": "90211"}]}'
response — 200 
{
  "count": 3,
  "crosswalk_release": { "year": 2026, "quarter": "A" },
  "results": [
    { "status": "exact", "zip5": "90210", "mac_code": "01182", "locality_code": "18", … },
    { "status": "exact", "zip5": "35801", "mac_code": "10112", "locality_code": "00", … },
    { "status": "ambiguous", "zip5": "90211", "mac_code": "01182", "locality_code": "18", … }
  ]
}

Locality directory

Medicare payment localities with GPCI rows in the selected PFS release. The locality field is the composite key the rate endpoints accept; name preserves the CMS label, while display_name, short_name, and path are UI-ready.

GET /v1/localities
year, quarter, as_of
Return localities with GPCI rows in the selected PFS release. Defaults to the current PFS release.
response — 200 
{
  "count": 109,
  "pfs_release": { "schedule": "pfs", "year": 2026, "quarter": "A", "revision": 1 },
  "localities": [
    {
      "id": 1,
      "locality": "01182-18",
      "mac": "01182",
      "code": "18",
      "state": "CA",
      "name": "LOS ANGELES-LONG BEACH-ANAHEIM (LOS ANGELES/ORANGE CNTY)",
      "display_name": "Los Angeles-Long Beach-Anaheim (Los Angeles/Orange County)",
      "short_name": "Los Angeles, Long Beach, and Anaheim",
      "path": "/localities/ca/los-angeles"
    }
  ]
}

GPCI rows

The raw work/PE/MP geographic practice cost indices behind every rate answer, one row per locality, normalized into a stable shape independent of how CMS orders or names the columns in a given quarter's GPCI{year}.csv. This is the same file rate lookups read from — reach for this endpoint when the GPCI values themselves are what you need to reproduce a calculation or audit a locality, not just the priced result.

The response keeps the release-stable MAC/locality key and payment indices. Locality names and states live in a mutable cross-release directory, so they are omitted rather than attached to a historical source row they may not have come from.

GET /v1/gpci
year, quarter, as_of
Return GPCI rows from the selected PFS release. Defaults to the current PFS release.
request 
curl https://localishealth.com/v1/gpci \
  -H "Authorization: Bearer sk_live_…"
response — 200 
{
  "release": { "schedule": "pfs", "year": 2026, "quarter": "A", "revision": 1 },
  "source": { "dataset": "gpci", "file": "GPCI2026.csv", "sha256": "f28471c5…", "row_count": 113 },
  "count": 113,
  "gpci": [
    {
      "locality": "01182-18",
      "mac": "01182",
      "code": "18",
      "work_gpci": 1.041,
      "work_gpci_no_floor": 1.041,
      "pe_gpci": 1.183,
      "mp_gpci": 0.664
    }
  ]
}

Single locality GPCI row

One locality's GPCI row, addressed by the same composite {mac}-{code} key the rate endpoints accept — see the locality directory to look one up.

GET /v1/gpci/{locality}
year, quarter, as_of
Return GPCI rows from the selected PFS release. Defaults to the current PFS release.
request 
curl https://localishealth.com/v1/gpci/01182-18 \
  -H "Authorization: Bearer sk_live_…"
response — 200 
{
  "release": { "schedule": "pfs", "year": 2026, "quarter": "A", "revision": 1 },
  "source": { "dataset": "gpci", "file": "GPCI2026.csv", "sha256": "f28471c5…", "row_count": 113 },
  "locality": "01182-18",
  "mac": "01182",
  "code": "18",
  "work_gpci": 1.041,
  "work_gpci_no_floor": 1.041,
  "pe_gpci": 1.183,
  "mp_gpci": 0.664
}

An unknown locality, or a locality with no GPCI row in the selected release, returns 404 with an error — never a fabricated zero.