cms_medicare_provider_services
Query Medicare Part-B provider utilization by NPI or state to retrieve services, beneficiaries, and payment amounts. Filter by provider type or HCPCS code for targeted analysis.
Instructions
Medicare Part-B provider utilization — HCPCS services rendered, beneficiaries served, and submitted / Medicare-allowed / Medicare-paid amounts (CMS 'Medicare Physician & Other Practitioners — by Provider and Service', keyless; data.cms.gov data-API). Input: npi (10-digit) OR state (2-letter) — at least ONE is REQUIRED (the table is 9.78M rows; an all-empty query is refused; providerType/hcpcsCode alone are NOT enough to scope). Optional providerType (exact CMS specialty, e.g. 'Family Practice'), hcpcsCode (e.g. '97110'), size (1–100, def 25), offset. Returns { services:[{ npi, providerName, credentials, providerType, city, state, zip, hcpcsCode, hcpcsDescription, totalBeneficiaries, totalServices, avgSubmittedCharge, avgMedicareAllowed, avgMedicarePayment }] } + honest _meta. ★HONESTY: totalAvailable is the EXACT count from a SEPARATE stats sub-query (…/data-viewer/stats → found_rows); if that count fails, totalAvailable is null + a disclosing note (never length-faked). hasMore = offset+returned < total. Aggregate/payment values: numeric-string → number|null (genuine 0 stays 0, absent → null, never 0-faked); NPI/HCPCS/names are null-never-empty-string. Genuine no-match → honest empty; 4xx → invalid_input/not_found; 5xx → THROWS; 200 non-array/non-JSON → schema_drift. PUBLIC PROVIDER-LEVEL AGGREGATE figures (no patient identifiers) for ONE annual vintage (dataset year disclosed in _meta) — utilization snapshot, NOT a fraud/quality/fitness determination.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| npi | No | A 10-digit National Provider Identifier (→ Rndrng_NPI), e.g. '1003000126'. Provide at least this OR `state`. Validated ^\d{10}$. | |
| size | No | Max provider-service rows to return (1–100, default 25). Offset-paginated. | |
| state | No | A 2-letter US state/territory code (→ Rndrng_Prvdr_State_Abrvtn), e.g. 'VA', 'CA'. Provide at least this OR `npi`. Validated ^[A-Za-z]{2}$. | |
| offset | No | Row offset for pagination (default 0). Page with _meta.pagination.nextOffset. | |
| hcpcsCode | No | An optional HCPCS/CPT service code filter (→ HCPCS_Cd), e.g. '97110', 'G0463'. Validated ^[A-Za-z0-9]{1,10}$. | |
| providerType | No | An optional specialty filter matching the CMS provider type EXACTLY (→ Rndrng_Prvdr_Type), e.g. 'Family Practice', 'Physical Therapist in Private Practice'. Allowed: letters/digits/space/& . , ( ) / ' - (≤100 chars). |