PFS Localities API¶

Complete API reference for querying Medicare Physician Fee Schedule (MPFS) Localities and Geographic Practice Cost Indices (GPCI).

Overview¶

The PFS Localities API provides access to geographic adjustment factors used in the Medicare Physician Fee Schedule. Medicare payments are adjusted geographically using three GPCI values to reflect the varying costs of providing services in different areas.

Base Path: /api/v1/pfs-localities

Authentication: Required for all endpoints (Bearer token or API Key)

Key Concepts¶

GPCI Values¶

Payments are adjusted using three Geographic Practice Cost Indices: - Work GPCI (gpci_work): Adjusts for the relative cost of physician work in an area. - Practice Expense GPCI (gpci_pe): Adjusts for the cost of maintaining a practice (rent, staff, supplies). - Malpractice GPCI (gpci_mp): Adjusts for the cost of professional liability insurance.

MACs and Localities¶

• MAC (Medicare Administrative Contractor): Private insurers that process Medicare claims for a specific jurisdiction.
• Locality: A specific geographic area within a MAC's jurisdiction, identified by a unique code.

Endpoints¶

Search Localities¶

Search and filter locality records with pagination.

Endpoint: GET /pfs-localities/search

Query Parameters:

Response:

{
  "data": [
    {
      "id": 101,
      "year": 2025,
      "locality": "0111205",
      "loc_description": "SAN FRANCISCO, CA",
      "mac": "01112",
      "mac_description": "NORTHERN CALIFORNIA",
      "gpci_work": 1.082,
      "gpci_pe": 1.254,
      "gpci_mp": 0.567,
      "start_date": 20250101,
      "end_date": 20251231
    }
  ],
  "count": 89
}

Example Request:

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.example.com/api/v1/pfs-localities/search?year=2025&search=California"

Lookup GPCI by Locality¶

Retrieve GPCI values for a specific locality and year. This is the primary endpoint for pricing calculations.

Endpoint: GET /pfs-localities/lookup/by-locality

Query Parameters:

Response:

{
  "id": 101,
  "year": 2025,
  "locality": "0111205",
  "loc_description": "SAN FRANCISCO, CA",
  "mac": "01112",
  "mac_description": "NORTHERN CALIFORNIA",
  "gpci_work": 1.082,
  "gpci_pe": 1.254,
  "gpci_mp": 0.567,
  "start_date": 20250101,
  "end_date": 20251231
}

Example Request:

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.example.com/api/v1/pfs-localities/lookup/by-locality?locality=0111205&year=2025"

Use Case: Calculate the geographically adjusted payment for a procedure: $$ \text{Payment} = [(\text{Work RVU} \times \text{Work GPCI}) + (\text{PE RVU} \times \text{PE GPCI}) + (\text{MP RVU} \times \text{MP GPCI})] \times \text{Conversion Factor} $$

Get Available Years¶

Get a list of all years available in the database.

Endpoint: GET /pfs-localities/lookup/years

Response:

{
  "years": [2025, 2024, 2023, 2022]
}

Get Available MACs¶

Get a list of Medicare Administrative Contractors, optionally filtered by year.

Endpoint: GET /pfs-localities/lookup/macs

Query Parameters:

Response:

{
  "macs": [
    {
      "mac": "01112",
      "mac_description": "NORTHERN CALIFORNIA"
    },
    {
      "mac": "01182",
      "mac_description": "SOUTHERN CALIFORNIA"
    }
  ]
}

Get Available Localities¶

Get a list of locality codes and descriptions, optionally filtered by year and MAC.

Endpoint: GET /pfs-localities/lookup/localities

Query Parameters:

Response:

{
  "localities": [
    {
      "locality": "0111205",
      "loc_description": "SAN FRANCISCO, CA",
      "mac": "01112"
    },
    {
      "locality": "0111206",
      "loc_description": "SAN MATEO, CA",
      "mac": "01112"
    }
  ]
}

Get Locality by ID¶

Retrieve a single locality record by its database ID.

Endpoint: GET /pfs-localities/{locality_id}

Path Parameters:

Get Summary Statistics¶

Get aggregate statistics about the localities database.

Endpoint: GET /pfs-localities/stats/summary

Response:

{
  "total_records": 890,
  "unique_localities": 112,
  "unique_macs": 15,
  "years": [2025, 2024],
  "records_by_year": [
    { "year": 2025, "count": 445 },
    { "year": 2024, "count": 445 }
  ]
}

Common Patterns¶

Pricing Calculation Example¶

To calculate the allowable amount for a CPT code in a specific location:

1. Get RVUs: Retrieve Relative Value Units (Work, PE, MP) for the CPT code from the Fee Schedule API.
2. Get GPCIs: Retrieve GPCI values (Work, PE, MP) for the location using lookup/by-locality.
3. Get Conversion Factor: Use the annual Conversion Factor (CF).
4. Calculate: Apply the formula:

def calculate_price(rvus, gpcis, conversion_factor):
    adjusted_work = rvus['work'] * gpcis['gpci_work']
    adjusted_pe = rvus['pe'] * gpcis['gpci_pe']
    adjusted_mp = rvus['mp'] * gpcis['gpci_mp']

    total_rvu = adjusted_work + adjusted_pe + adjusted_mp
    return total_rvu * conversion_factor

Finding the Correct Locality¶

If you only have a ZIP code, you first need to map the ZIP code to a locality code. (See the ZIP9 Data API for ZIP-to-Locality mapping).

Error Handling¶