The CMS NPI Registry API, version 2.1
(https://npiregistry.cms.hhs.gov/api/?version=2.1, no key): one
provider by NPI, and searches by name, organization, taxonomy and
location.
Search limits. A request returns up to 200 records (default 10)
and can skip up to 1,000, so one set of criteria reaches 1,200
records over six requests. The API doesn't report a total, and it
answers a limit or skip above the maximum as if it were the
maximum, without saying so: past 1,000, skip returns the same
records again. So search caps limit and refuses a higher skip.
next-page gives the next skip, and collect follows it to the
end of that reach.
Every function takes an optional trailing opts Map: the criteria
listed at search-params, limit, skip, and base-url.
Context Vars
nppes.base-url
Values
DEFAULT_LIMIT
DEFAULT_LIMIT: Int 10
MAX_LIMIT
MAX_LIMIT: Int 200
MAX_SKIP
MAX_SKIP: Int 1000
PARAMS
PARAMS: Map {
number: "number",
enumeration-type: "enumeration_type",
taxonomy-description: "taxonomy_description",
name-purpose: "name_purpose",
first-name: "first_name",
last-name: "last_name",
organization-name: "organization_name",
address-purpose: "address_purpose",
city: "city",
state: "state",
postal-code: "postal_code",
country-code: "country_code"
}
VERSION
VERSION: Str "2.1"
Functions
address-for
fn (provider: Any, purpose: Str): Map?
alias-param
fn (value: Any): Str?
collect
fn (fetch: Fn, opts: Map, limit: Int): Vec
Follow pages until limit records or the API's reach. fetch takes
opts (with limit and skip set) and returns one page. An Err on
any page is returned in place of the records. One search reaches
skip 1,000 plus a page, so 1,200 records at the default 200 a page.
Exactly that many means there may be more: narrow the criteria, by
state or postal code, and collect again.
Example
rows ::nppes/collect((o) { ::nppes/organizations("mayo clinic*", o) }, {state: "MN"}, 500)
collect-pages
fn (fetch: Fn, opts: Map, start: Int, limit: Int, acc: Vec): Vec
final-skip
fn (page: Any, opts: Map): Int?
get-provider
fn (npi: Any): Map?
fn (npi: Any, opts: Map): Map?
One provider by NPI, or null when the registry has none. An NPI that
isn't 10 digits is an Err from the API; is-npi checks one first.
Example
provider ::nppes/get-provider("1881018208")
provider.basic.organization_name // "MAYO CLINIC"
::nppes/primary-taxonomy(provider).desc
individuals
fn (last-name: Str): Map
fn (last-name: Str, opts: Map): Map
Search individual providers (Type 1 NPIs) by last name, with first-name and any other criteria in opts.
is-active
fn (provider: Any): Bool
True when the record's basic.status is "A" (pure).
is-npi
fn (npi: Any): Bool
True for a syntactically valid NPI: 10 digits with a valid Luhn check digit, computed with the 80840 health-industry prefix (pure). It says nothing about whether the NPI was issued.
location-address
fn (provider: Any): Map?
A provider's primary practice location address, or null (pure). Other locations are in practiceLocations.
luhn-sum
fn (digits: Str): Int
mailing-address
fn (provider: Any): Map?
A provider's mailing address, or null (pure).
next-page
fn (page: Any, opts: Map): Int?
The skip after page, or null when the page came back short or the
next skip would pass 1,000 (pure). opts are the ones that fetched
page. The API gives no total, so a full last page gets one more,
empty, request.
organizations
fn (name: Str): Map
fn (name: Str, opts: Map): Map
Search organizational providers (Type 2 NPIs) by name, with any other criteria in opts.
page-limit
fn (opts: Map): Int
opts.limit, capped at 200, or 10 when unset (pure).
primary-taxonomy
fn (provider: Any): Map?
The taxonomy marked primary, {code, desc, license, state, primary, taxonomy_group}, or null (pure).
registry-get
fn (opts: Map): Any
results
fn (page: Any): Vec<Map>
The provider records in a page (pure).
search
fn (opts: Map): Map
Search the registry. Returns the API's page: result_count (the
records in this page, not the total) and results. Read it with
results. Criteria the API rejects are an Err, such as state alone
or a wildcard after one letter. An Err too when skip is over 1,000,
which the API would answer with repeated records.
Example
page ::nppes/search({organization-name: "mayo clinic*", state: "MN", limit: 50})
first(::nppes/results(page)).basic.organization_name
search-params
fn (opts: Map): Map
Query parameters for a search (pure). first-name, last-name,
organization-name, taxonomy-description, city and postal-code
take a trailing * after at least two characters.
| opts key | Meaning |
|---|---|
number | A 10-digit NPI |
enumeration-type | "NPI-1" (individuals) or "NPI-2" (organizations); needs other criteria |
first-name, last-name | Individuals, or authorized officials with name-purpose: "AO" |
use-first-name-alias | true (the API's default) also matches similar first names; false is exact |
name-purpose | "AO" or "PROVIDER" |
organization-name | Organizations; checks every name on the record, including former and other names |
taxonomy-description | An exact taxonomy description or specialty |
address-purpose | "LOCATION", "MAILING", "PRIMARY" or "SECONDARY" |
city, postal-code | A 5-digit code also matches ZIP+4 |
state | Two letters; needs another criterion besides enumeration-type and country-code |
country-code | Two letters; "US" needs other criteria |
limit, skip | Page size up to 200; records to skip, up to 1,000 |